auramaxx 1.0.0-alpha.4

package/server/routes/credentials.ts

@@ -0,0 +1,1290 @@
+import { Request, Response, Router } from 'express';
+import {
+  archiveCredential,
+  createCredential,
+  deleteArchivedCredential,
+  deleteCredential,
+  findCredentialLocation,
+  getCredential,
+  listCredentials,
+  purgeDeletedCredentials,
+  readCredentialSecrets,
+  restoreArchivedCredential,
+  restoreDeletedCredential,
+  updateCredential,
+  type CredentialLocation,
+} from '../lib/credentials';
+import { getErrorMessage } from '../lib/error';
+import { hasAnyPermission, isAdmin } from '../lib/permissions';
+import { recordCredentialRead } from '../lib/sessions';
+import { CredentialField, CredentialFile, CredentialType } from '../types';
+import { requireWalletAuth } from '../middleware/auth';
+import { matchesScope, normalizeScope, resolveExcludeFields } from '../lib/credential-scope';
+import { encryptToAgentPubkey } from '../lib/credential-transport';
+import { logEvent } from '../lib/logger';
+import { generateTOTP, findTotpField } from '../lib/totp';
+import { readOAuth2SecretsWithRefresh, OAUTH2_DEFAULT_EXCLUDE_FIELDS } from '../lib/oauth2-refresh';
+import { getLinkedVaultGroup, getPrimaryVaultId } from '../lib/cold';
+import { evaluateCredentialAccess } from '../lib/credential-access-policy';
+import { writeCredentialAccessAudit } from '../lib/credential-access-audit';
+import { computeGpgFingerprint, computeSshFingerprint } from '../lib/key-fingerprint';
+import { events } from '../lib/events';
+import {
+  buildCredentialHealthRows,
+  summarizeCredentialHealthFlags,
+} from '../lib/credential-health';
+
+const router = Router();
+
+const VALID_CREDENTIAL_TYPES = new Set<CredentialType>([
+  'login',
+  'card',
+  'note',
+  'api',
+  'apikey',
+  'custom',
+  'passkey',
+  'oauth2',
+  'ssh',
+  'gpg',
+]);
+
+const VALID_FIELD_TYPES = new Set(['text', 'secret', 'url', 'email', 'number']);
+const VALID_CREDENTIAL_LOCATIONS = new Set<CredentialLocation>(['active', 'archive', 'recently_deleted']);
+
+router.use(requireWalletAuth);
+
+function parseCredentialLocation(value: unknown, fallback: CredentialLocation = 'active'): CredentialLocation | null {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value !== 'string') return null;
+  if (!VALID_CREDENTIAL_LOCATIONS.has(value as CredentialLocation)) return null;
+  return value as CredentialLocation;
+}
+
+function toMetadata(credential: CredentialFile): Omit<CredentialFile, 'encrypted'> & { has_totp?: boolean } {
+  const { encrypted: _encrypted, ...metadata } = credential;
+  if (credential.meta?.has_totp === true) {
+    return { ...metadata, has_totp: true };
+  }
+  return metadata;
+}
+
+function normalizeName(name: string): string {
+  return name.trim().normalize('NFKC');
+}
+
+function normalizeMeta(meta: Record<string, unknown>): Record<string, unknown> {
+  const normalized: Record<string, unknown> = { ...meta };
+
+  if (normalized.tags !== undefined) {
+    if (!Array.isArray(normalized.tags)) {
+      throw new Error('meta.tags must be an array');
+    }
+    normalized.tags = normalized.tags
+      .filter(tag => typeof tag === 'string')
+      .map(tag => normalizeScope(tag))
+      .filter(tag => tag.length > 0);
+  }
+
+  if (normalized.hosts !== undefined) {
+    if (!Array.isArray(normalized.hosts)) {
+      throw new Error('meta.hosts must be an array');
+    }
+    normalized.hosts = normalized.hosts
+      .filter(host => typeof host === 'string')
+      .map(host => host.trim())
+      .filter(host => host.length > 0);
+  }
+
+  if (normalized.walletLink !== undefined) {
+    if (!normalized.walletLink || typeof normalized.walletLink !== 'object' || Array.isArray(normalized.walletLink)) {
+      throw new Error('meta.walletLink must be an object');
+    }
+
+    const rawWalletLink = normalized.walletLink as Record<string, unknown>;
+    const walletAddress = typeof rawWalletLink.walletAddress === 'string' ? rawWalletLink.walletAddress.trim() : '';
+    const chain = typeof rawWalletLink.chain === 'string' ? rawWalletLink.chain.trim() : '';
+    const tier = rawWalletLink.tier;
+    const source = rawWalletLink.source;
+    const label = typeof rawWalletLink.label === 'string' ? rawWalletLink.label.trim() : undefined;
+    const version = typeof rawWalletLink.version === 'number' ? rawWalletLink.version : 1;
+
+    if (!walletAddress) throw new Error('meta.walletLink.walletAddress is required');
+    if (!chain) throw new Error('meta.walletLink.chain is required');
+    if (tier !== 'cold' && tier !== 'hot') throw new Error('meta.walletLink.tier must be "cold" or "hot"');
+    if (source !== 'existing' && source !== 'created') throw new Error('meta.walletLink.source must be "existing" or "created"');
+    if (version !== 1) throw new Error('meta.walletLink.version must be 1');
+
+    normalized.walletLink = {
+      version: 1,
+      walletAddress,
+      chain,
+      tier,
+      source,
+      ...(label ? { label } : {}),
+      linkedAt: new Date().toISOString(),
+    };
+  }
+
+  return normalized;
+}
+
+function isPrimaryVault(vaultId: string): boolean {
+  const primaryVaultId = getPrimaryVaultId();
+  if (primaryVaultId && vaultId === primaryVaultId) return true;
+  return vaultId === 'primary';
+}
+
+
+function inferSshKeyType(keyText: string | undefined): string {
+  if (!keyText) return 'other';
+  const key = keyText.toLowerCase();
+  if (key.includes('ed25519')) return 'ed25519';
+  if (key.includes('rsa')) return 'rsa';
+  if (key.includes('ecdsa')) return 'ecdsa';
+  return 'other';
+}
+
+function enforceKeyCredentialMetadata(
+  type: CredentialType,
+  meta: Record<string, unknown>,
+  sensitiveFields: CredentialField[],
+): Record<string, unknown> {
+  if (type !== 'ssh' && type !== 'gpg') return meta;
+
+  const nextMeta: Record<string, unknown> = { ...meta };
+  delete nextMeta.fingerprint;
+  const fieldMap = new Map(sensitiveFields.map(field => [field.key, field.value]));
+  const privateKey = fieldMap.get('private_key')?.trim() || '';
+  const publicKey = typeof nextMeta.public_key === 'string' ? nextMeta.public_key : '';
+
+  if (!privateKey) {
+    throw new Error(`${type} requires sensitive field private_key`);
+  }
+
+  if (type === 'ssh') {
+    const computed = computeSshFingerprint(publicKey || privateKey);
+    if (computed) nextMeta.fingerprint = computed;
+    if (!nextMeta.key_type || typeof nextMeta.key_type !== 'string') {
+      nextMeta.key_type = inferSshKeyType(publicKey || privateKey);
+    }
+  }
+
+  if (type === 'gpg') {
+    const computed = computeGpgFingerprint(publicKey || privateKey);
+    if (computed) nextMeta.fingerprint = computed;
+  }
+
+  return nextMeta;
+}
+
+const OAUTH2_REQUIRED_SECRET_FIELDS = ['access_token', 'refresh_token', 'client_id', 'client_secret'];
+const OAUTH2_REAUTH_RESET_FIELDS = new Set(OAUTH2_REQUIRED_SECRET_FIELDS);
+
+function shouldClearOAuth2ReauthMarker(credentialType: string, sensitiveFields: CredentialField[] | undefined) {
+  if (credentialType !== 'oauth2' || !sensitiveFields || sensitiveFields.length === 0) {
+    return false;
+  }
+
+  return sensitiveFields.some(field => OAUTH2_REAUTH_RESET_FIELDS.has(field.key));
+}
+
+function validateOAuth2Meta(meta: Record<string, unknown>) {
+  const tokenEndpoint = meta.token_endpoint;
+  if (typeof tokenEndpoint !== 'string' || tokenEndpoint.trim().length === 0) {
+    throw new Error('oauth2 requires meta.token_endpoint');
+  }
+
+  const expiresAt = meta.expires_at;
+  if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) {
+    throw new Error('oauth2 requires numeric meta.expires_at (unix timestamp seconds)');
+  }
+}
+
+function validateOAuth2RequiredFields(fields: CredentialField[]) {
+  const fieldMap = new Map(fields.map(field => [field.key, field.value]));
+  for (const key of OAUTH2_REQUIRED_SECRET_FIELDS) {
+    const value = fieldMap.get(key);
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      throw new Error(`oauth2 requires sensitive field ${key}`);
+    }
+  }
+}
+
+function mergeOAuth2Fields(base: CredentialField[], updates: CredentialField[] = []): CredentialField[] {
+  if (updates.length === 0) return base;
+
+  const merged = new Map<string, CredentialField>();
+  for (const field of base) merged.set(field.key, field);
+  for (const field of updates) merged.set(field.key, field);
+  return [...merged.values()];
+}
+
+function parseFields(value: unknown): CredentialField[] {
+  if (!Array.isArray(value)) return [];
+
+  const fields: CredentialField[] = [];
+  for (const rawField of value) {
+    if (!rawField || typeof rawField !== 'object') continue;
+    const raw = rawField as Record<string, unknown>;
+    if (typeof raw.key !== 'string' || typeof raw.value !== 'string') continue;
+
+    const key = raw.key.trim();
+    if (!key) continue;
+
+    const type = typeof raw.type === 'string' && VALID_FIELD_TYPES.has(raw.type)
+      ? raw.type as CredentialField['type']
+      : 'text';
+
+    fields.push({
+      key,
+      value: raw.value,
+      type,
+      sensitive: !!raw.sensitive,
+    });
+  }
+
+  return fields;
+}
+
+function mergeNonSensitiveFieldsIntoMeta(
+  meta: Record<string, unknown>,
+  fields: CredentialField[],
+): Record<string, unknown> {
+  const merged = { ...meta };
+  for (const field of fields) {
+    if (!field.sensitive && merged[field.key] === undefined) {
+      merged[field.key] = field.value;
+    }
+  }
+  return merged;
+}
+
+function canReadCredential(req: Request, credential: CredentialFile): boolean {
+  const auth = req.auth!;
+  if (isAdmin(auth)) return true;
+  if (!hasAnyPermission(auth.token.permissions, ['secret:read'])) return false;
+  const scopes = auth.token.credentialAccess?.read || [];
+  return matchesScope(credential, scopes);
+}
+
+function canWriteCredential(req: Request, credential: CredentialFile): boolean {
+  const auth = req.auth!;
+  if (isAdmin(auth)) return true;
+  if (!hasAnyPermission(auth.token.permissions, ['secret:write'])) return false;
+  const scopes = auth.token.credentialAccess?.write || [];
+  return matchesScope(credential, scopes);
+}
+
+function credentialActor(req: Request): {
+  actorType: 'admin' | 'agent';
+  agentId?: string;
+  tokenHash?: string;
+} {
+  const auth = req.auth!;
+  return {
+    actorType: isAdmin(auth) ? 'admin' : 'agent',
+    agentId: auth.token.agentId,
+    tokenHash: auth.tokenHash,
+  };
+}
+
+function emitCredentialChanged(
+  req: Request,
+  credential: CredentialFile,
+  change:
+    | 'created'
+    | 'updated'
+    | 'archived'
+    | 'moved_to_recently_deleted'
+    | 'restored_to_active'
+    | 'restored_to_archive'
+    | 'purged',
+  location?: {
+    fromLocation?: CredentialLocation;
+    toLocation?: CredentialLocation;
+  },
+): void {
+  const actor = credentialActor(req);
+  events.credentialChanged({
+    credentialId: credential.id,
+    vaultId: credential.vaultId,
+    change,
+    actorType: actor.actorType,
+    agentId: actor.agentId,
+    tokenHash: actor.tokenHash,
+    fromLocation: location?.fromLocation,
+    toLocation: location?.toLocation,
+  });
+}
+
+function emitCredentialAccessed(
+  req: Request,
+  credential: CredentialFile,
+  input: {
+    action: 'credentials.read' | 'credentials.totp';
+    allowed: boolean;
+    reasonCode: string;
+    httpStatus: number;
+  },
+): void {
+  const actor = credentialActor(req);
+  events.credentialAccessed({
+    credentialId: credential.id,
+    vaultId: credential.vaultId,
+    action: input.action,
+    allowed: input.allowed,
+    reasonCode: input.reasonCode,
+    httpStatus: input.httpStatus,
+    actorType: actor.actorType,
+    agentId: actor.agentId,
+    tokenHash: actor.tokenHash,
+  });
+}
+
+function credentialAccessErrorMessage(reasonCode: string, action: 'credentials.read' | 'credentials.totp'): string {
+  if (reasonCode === 'TOKEN_TTL_EXPIRED') return 'Credential access TTL expired';
+  if (reasonCode === 'TOKEN_MAX_READS_EXCEEDED') return 'Credential read limit reached';
+  if (reasonCode === 'CREDENTIAL_RATE_LIMIT_EXCEEDED') {
+    return action === 'credentials.totp'
+      ? 'TOTP rate limit exceeded (max 10/min)'
+      : 'Credential rate limit exceeded';
+  }
+  if (reasonCode === 'CREDENTIAL_SCOPE_DENIED') return 'Credential read scope denied';
+  if (reasonCode === 'TOKEN_PERMISSION_DENIED') return 'totp:read permission required';
+  if (reasonCode === 'TOKEN_AGENT_PUBKEY_MISSING') return 'agentPubkey is required on token for credential reads';
+  if (reasonCode === 'CREDENTIAL_TOTP_NOT_CONFIGURED') return 'Credential has no TOTP secret';
+  return reasonCode;
+}
+
+async function writeDeniedCredentialAccess(params: {
+  req: Request;
+  credential: CredentialFile;
+  action: 'credentials.read' | 'credentials.totp';
+  reasonCode: 'TOKEN_TTL_EXPIRED' | 'TOKEN_MAX_READS_EXCEEDED' | 'CREDENTIAL_RATE_LIMIT_EXCEEDED' | 'CREDENTIAL_SCOPE_DENIED' | 'TOKEN_PERMISSION_DENIED' | 'TOKEN_AGENT_PUBKEY_MISSING' | 'CREDENTIAL_TOTP_NOT_CONFIGURED';
+  httpStatus: number;
+  metadata?: Record<string, unknown>;
+}): Promise<void> {
+  const auth = params.req.auth!;
+  await writeCredentialAccessAudit({
+    credentialId: params.credential.id,
+    vaultId: params.credential.vaultId,
+    action: params.action,
+    allowed: false,
+    reasonCode: params.reasonCode,
+    httpStatus: params.httpStatus,
+    tokenHash: auth.tokenHash,
+    agentId: auth.token.agentId,
+    requestId: params.req.header('x-request-id') ?? undefined,
+    actorType: isAdmin(auth) ? 'admin' : 'agent',
+    metadata: params.metadata,
+  });
+  emitCredentialAccessed(params.req, params.credential, {
+    action: params.action,
+    allowed: false,
+    reasonCode: params.reasonCode,
+    httpStatus: params.httpStatus,
+  });
+}
+
+type HealthScanJobStatus = 'queued' | 'running' | 'complete' | 'failed' | 'expired';
+
+const healthScanJobs = new Map<string, {
+  status: HealthScanJobStatus;
+  createdAt: number;
+  updatedAt: number;
+  error?: string;
+}>();
+
+function newScanId(): string {
+  return `scan-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function listHealthCredentials(req: Request): CredentialFile[] {
+  const auth = req.auth!;
+  const reuseScopeMode = req.query.reuseScope === 'vault' ? 'vault' : 'group';
+  const selectedVault = typeof req.query.vault === 'string' ? req.query.vault : undefined;
+
+  const candidates = listCredentials();
+  const readable = isAdmin(auth)
+    ? candidates
+    : candidates.filter(credential => matchesScope(credential, auth.token.credentialAccess?.read || []));
+
+  if (!selectedVault) return readable;
+  if (reuseScopeMode === 'vault') return readable.filter(c => c.vaultId === selectedVault);
+
+  const group = new Set(getLinkedVaultGroup(selectedVault));
+  return readable.filter(c => group.has(c.vaultId));
+}
+
+function pruneExpiredHealthJobs(): void {
+  const now = Date.now();
+  for (const [id, job] of healthScanJobs.entries()) {
+    const terminal = job.status === 'complete' || job.status === 'failed';
+    if (!terminal) continue;
+    if (now - job.updatedAt > 30 * 60 * 1000) {
+      healthScanJobs.set(id, { ...job, status: 'expired', updatedAt: now });
+    }
+  }
+}
+
+// POST /credentials — create
+router.post('/', (req: Request, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['secret:write'])) {
+      res.status(403).json({ success: false, error: 'secret:write permission required' });
+      return;
+    }
+
+    const vaultId = typeof req.body?.vaultId === 'string' ? req.body.vaultId : '';
+    const type = typeof req.body?.type === 'string' ? req.body.type : '';
+    const rawName = typeof req.body?.name === 'string' ? req.body.name : '';
+
+    if (!vaultId || !type || !rawName) {
+      res.status(400).json({ success: false, error: 'vaultId, type, and name are required' });
+      return;
+    }
+    if (!VALID_CREDENTIAL_TYPES.has(type as CredentialType)) {
+      res.status(400).json({ success: false, error: `Invalid credential type: ${type}` });
+      return;
+    }
+
+    const name = normalizeName(rawName);
+    const rawMeta = req.body?.meta && typeof req.body.meta === 'object' && !Array.isArray(req.body.meta)
+      ? req.body.meta as Record<string, unknown>
+      : {};
+    const normalizedMeta = normalizeMeta(rawMeta);
+    const rawFields = parseFields(req.body?.fields);
+    const sensitiveFields = parseFields(req.body?.sensitiveFields);
+    const fieldsToEncrypt = sensitiveFields.length > 0
+      ? sensitiveFields
+      : rawFields.filter(field => field.sensitive);
+    let finalMeta = mergeNonSensitiveFieldsIntoMeta(normalizedMeta, rawFields);
+
+    if (type === 'oauth2') {
+      if (!isPrimaryVault(vaultId)) {
+        res.status(400).json({ success: false, error: 'oauth2 credentials must be stored in the primary vault' });
+        return;
+      }
+      validateOAuth2Meta(finalMeta);
+      validateOAuth2RequiredFields(fieldsToEncrypt.length > 0 ? fieldsToEncrypt : rawFields);
+    }
+
+    if (type === 'ssh' || type === 'gpg') {
+      finalMeta = enforceKeyCredentialMetadata(type as CredentialType, finalMeta, fieldsToEncrypt);
+    }
+
+    if (!isAdmin(auth)) {
+      const candidate: CredentialFile = {
+        id: 'pending',
+        vaultId,
+        type: type as CredentialType,
+        name,
+        meta: finalMeta,
+        encrypted: { ciphertext: '', iv: '', salt: '', mac: '' },
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+      const scopes = auth.token.credentialAccess?.write || [];
+      if (!matchesScope(candidate, scopes)) {
+        res.status(403).json({ success: false, error: 'Credential write scope denied' });
+        return;
+      }
+    }
+
+    // Auto-set has_totp flag in meta if TOTP field present (check both 'totp' and 'otp' for compat)
+    if (findTotpField(fieldsToEncrypt)) {
+      finalMeta.has_totp = true;
+    }
+
+    const created = createCredential(vaultId, type as CredentialType, name, finalMeta, fieldsToEncrypt);
+    emitCredentialChanged(req, created, 'created', { toLocation: 'active' });
+    res.json({ success: true, credential: toMetadata(created) });
+  } catch (error) {
+    res.status(400).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// GET /credentials — list metadata
+router.get('/', async (req: Request, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['secret:read'])) {
+      res.status(403).json({ success: false, error: 'secret:read permission required' });
+      return;
+    }
+
+    const vaultId = typeof req.query.vault === 'string' ? req.query.vault : undefined;
+    const type = typeof req.query.type === 'string' ? req.query.type : undefined;
+    const tag = typeof req.query.tag === 'string' ? req.query.tag : undefined;
+    const query = typeof req.query.q === 'string' ? req.query.q : undefined;
+    const location = parseCredentialLocation(req.query.location, 'active');
+
+    if (type && !VALID_CREDENTIAL_TYPES.has(type as CredentialType)) {
+      res.status(400).json({ success: false, error: `Invalid credential type: ${type}` });
+      return;
+    }
+    if (!location) {
+      res.status(400).json({ success: false, error: 'Invalid location. Expected active, archive, or recently_deleted' });
+      return;
+    }
+
+    const credentials = listCredentials({
+      vaultId,
+      type: type as CredentialType | undefined,
+      tag,
+      query,
+    }, location);
+
+    const filtered = isAdmin(auth)
+      ? credentials
+      : credentials.filter(credential => matchesScope(credential, auth.token.credentialAccess?.read || []));
+
+    const includeHealth = req.query.health === '1' || req.query.health === 'true';
+
+    if (!includeHealth) {
+      res.json({
+        success: true,
+        credentials: filtered.map(toMetadata),
+      });
+      return;
+    }
+
+    const rows = await buildCredentialHealthRows(filtered, readCredentialSecrets);
+    const rowById = new Map(rows.map(row => [row.id, row.health]));
+
+    res.json({
+      success: true,
+      credentials: filtered.map(credential => ({
+        ...toMetadata(credential),
+        health: rowById.get(credential.id)
+          ? { status: rowById.get(credential.id)!.status }
+          : undefined,
+      })),
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// GET /credentials/health/summary — aggregate credential health
+router.get('/health/summary', async (req: Request, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['secret:read'])) {
+      res.status(403).json({ success: false, error: 'secret:read permission required' });
+      return;
+    }
+
+    pruneExpiredHealthJobs();
+
+    const credentials = listHealthCredentials(req);
+    const rows = await buildCredentialHealthRows(credentials, readCredentialSecrets);
+    const summary = summarizeCredentialHealthFlags(rows.map((row) => row.health.flags));
+
+    res.json({
+      success: true,
+      summary: {
+        totalAnalyzed: summary.total,
+        safe: summary.safe,
+        weak: summary.weak,
+        reused: summary.reused,
+        breached: summary.breached,
+        unknown: summary.unknown,
+        lastScanAt: new Date().toISOString(),
+      },
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// GET /credentials/health — per-credential health rows
+router.get('/health', async (req: Request, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['secret:read'])) {
+      res.status(403).json({ success: false, error: 'secret:read permission required' });
+      return;
+    }
+
+    pruneExpiredHealthJobs();
+
+    const credentials = listHealthCredentials(req);
+    const rows = await buildCredentialHealthRows(credentials, readCredentialSecrets);
+
+    res.json({ success: true, credentials: rows });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// POST /credentials/health/rescan — async job kickoff
+router.post('/health/rescan', async (req: Request, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['secret:read'])) {
+      res.status(403).json({ success: false, error: 'secret:read permission required' });
+      return;
+    }
+
+    const scanId = newScanId();
+    const now = Date.now();
+    healthScanJobs.set(scanId, { status: 'queued', createdAt: now, updatedAt: now });
+
+    void (async () => {
+      try {
+        healthScanJobs.set(scanId, { status: 'running', createdAt: now, updatedAt: Date.now() });
+        const credentials = listHealthCredentials(req);
+        await buildCredentialHealthRows(credentials, readCredentialSecrets);
+        healthScanJobs.set(scanId, { status: 'complete', createdAt: now, updatedAt: Date.now() });
+      } catch (error) {
+        healthScanJobs.set(scanId, {
+          status: 'failed',
+          createdAt: now,
+          updatedAt: Date.now(),
+          error: getErrorMessage(error),
+        });
+      }
+    })();
+
+    res.json({ accepted: true, scanId });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// GET /credentials/health/rescan/:scanId — read async scan status
+router.get('/health/rescan/:scanId', (req: Request<{ scanId: string }>, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['secret:read'])) {
+      res.status(403).json({ success: false, error: 'secret:read permission required' });
+      return;
+    }
+
+    pruneExpiredHealthJobs();
+
+    const scan = healthScanJobs.get(req.params.scanId);
+    if (!scan) {
+      res.status(404).json({ success: false, error: 'Scan job not found' });
+      return;
+    }
+
+    res.json({
+      success: true,
+      scanId: req.params.scanId,
+      scan: {
+        status: scan.status,
+        createdAt: new Date(scan.createdAt).toISOString(),
+        updatedAt: new Date(scan.updatedAt).toISOString(),
+        error: scan.error,
+      },
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// GET /credentials/:id — metadata
+router.get('/:id', (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const credential = getCredential(req.params.id);
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+
+    if (!canReadCredential(req, credential)) {
+      res.status(403).json({ success: false, error: 'Credential read scope denied' });
+      return;
+    }
+
+    res.json({ success: true, credential: toMetadata(credential) });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// PUT /credentials/:id — update
+router.put('/:id', (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const credential = getCredential(req.params.id);
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+    if (!canWriteCredential(req, credential)) {
+      res.status(403).json({ success: false, error: 'Credential write scope denied' });
+      return;
+    }
+
+    let updatedMeta: Record<string, unknown> | undefined;
+    const hasMetaInput = req.body && Object.prototype.hasOwnProperty.call(req.body, 'meta');
+    if (hasMetaInput) {
+      if (!req.body.meta || typeof req.body.meta !== 'object' || Array.isArray(req.body.meta)) {
+        res.status(400).json({ success: false, error: 'meta must be an object' });
+        return;
+      }
+      updatedMeta = normalizeMeta(req.body.meta as Record<string, unknown>);
+    }
+
+    const fields = parseFields(req.body?.fields);
+    if (fields.length > 0 || updatedMeta) {
+      const baseMeta = updatedMeta || { ...credential.meta };
+      updatedMeta = mergeNonSensitiveFieldsIntoMeta(baseMeta, fields);
+    }
+
+    let sensitiveFields: CredentialField[] | undefined;
+    const hasSensitiveInput = req.body && Object.prototype.hasOwnProperty.call(req.body, 'sensitiveFields');
+    if (hasSensitiveInput) {
+      sensitiveFields = parseFields(req.body.sensitiveFields);
+    } else {
+      const sensitiveFromFields = fields.filter(field => field.sensitive);
+      if (sensitiveFromFields.length > 0) {
+        sensitiveFields = sensitiveFromFields;
+      }
+    }
+
+    // Auto-set has_totp flag in meta if TOTP field present in update
+    if (sensitiveFields && findTotpField(sensitiveFields)) {
+      if (!updatedMeta) updatedMeta = { ...credential.meta };
+      updatedMeta.has_totp = true;
+    }
+
+    const rawName = typeof req.body?.name === 'string' ? normalizeName(req.body.name) : undefined;
+
+    if (credential.type === 'oauth2') {
+      const baseMeta = credential.meta as Record<string, unknown>;
+      const updatedReauthMeta = shouldClearOAuth2ReauthMarker(credential.type, sensitiveFields)
+        ? {
+            ...baseMeta,
+            needs_reauth: false,
+            reauth_reason: null,
+          }
+        : baseMeta;
+
+      const finalMeta = { ...baseMeta, ...updatedReauthMeta, ...updatedMeta };
+      validateOAuth2Meta(finalMeta);
+      if (!isPrimaryVault(credential.vaultId)) {
+        res.status(400).json({ success: false, error: 'oauth2 credentials must be stored in the primary vault' });
+        return;
+      }
+
+      if (sensitiveFields !== undefined) {
+        const existingSensitiveFields = readCredentialSecrets(req.params.id);
+        const effectiveSensitiveFields = mergeOAuth2Fields(existingSensitiveFields, sensitiveFields);
+        validateOAuth2RequiredFields(effectiveSensitiveFields);
+      }
+
+      updatedMeta = finalMeta;
+    }
+
+
+    if ((credential.type === 'ssh' || credential.type === 'gpg') && updatedMeta) {
+      const existingSensitiveFields = readCredentialSecrets(credential.id);
+      const effectiveSensitiveFields = sensitiveFields !== undefined
+        ? mergeOAuth2Fields(existingSensitiveFields, sensitiveFields)
+        : existingSensitiveFields;
+      updatedMeta = enforceKeyCredentialMetadata(credential.type, updatedMeta, effectiveSensitiveFields);
+    }
+
+    const updated = updateCredential(req.params.id, {
+      name: rawName,
+      meta: updatedMeta,
+      sensitiveFields,
+    });
+
+    emitCredentialChanged(req, updated, 'updated', { toLocation: 'active' });
+    res.json({ success: true, credential: toMetadata(updated) });
+  } catch (error) {
+    res.status(400).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// DELETE /credentials/:id — lifecycle delete:
+// active -> archive, archive -> recently_deleted, recently_deleted -> permanent delete
+router.delete('/:id', (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const location = parseCredentialLocation(req.query.location, 'active');
+    if (!location) {
+      res.status(400).json({ success: false, error: 'Invalid location. Expected active, archive, or recently_deleted' });
+      return;
+    }
+
+    const credential = getCredential(req.params.id, location);
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+    if (!canWriteCredential(req, credential)) {
+      res.status(403).json({ success: false, error: 'Credential write scope denied' });
+      return;
+    }
+
+    if (location === 'active') {
+      const archived = archiveCredential(req.params.id);
+      if (archived) {
+        emitCredentialChanged(req, archived, 'archived', {
+          fromLocation: 'active',
+          toLocation: 'archive',
+        });
+      }
+      res.json({ success: true, action: 'archived', credential: archived ? toMetadata(archived) : null });
+      return;
+    }
+
+    if (location === 'archive') {
+      const deleted = deleteArchivedCredential(req.params.id);
+      if (deleted) {
+        emitCredentialChanged(req, deleted, 'moved_to_recently_deleted', {
+          fromLocation: 'archive',
+          toLocation: 'recently_deleted',
+        });
+      }
+      res.json({ success: true, action: 'moved_to_recently_deleted', credential: deleted ? toMetadata(deleted) : null });
+      return;
+    }
+
+    const deleted = deleteCredential(req.params.id, 'recently_deleted');
+    if (deleted) {
+      emitCredentialChanged(req, credential, 'purged', {
+        fromLocation: 'recently_deleted',
+      });
+    }
+    res.json({ success: true, action: 'purged', deleted });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// POST /credentials/:id/restore — restore from archive/recently_deleted
+router.post('/:id/restore', (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const from = parseCredentialLocation(req.body?.from ?? req.query.from, 'archive');
+    if (!from || from === 'active') {
+      res.status(400).json({ success: false, error: 'Invalid from location. Expected archive or recently_deleted' });
+      return;
+    }
+
+    const credential = getCredential(req.params.id, from);
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+    if (!canWriteCredential(req, credential)) {
+      res.status(403).json({ success: false, error: 'Credential write scope denied' });
+      return;
+    }
+
+    if (from === 'archive') {
+      const restored = restoreArchivedCredential(req.params.id);
+      if (restored) {
+        emitCredentialChanged(req, restored, 'restored_to_active', {
+          fromLocation: 'archive',
+          toLocation: 'active',
+        });
+      }
+      res.json({ success: true, action: 'restored_to_active', credential: restored ? toMetadata(restored) : null });
+      return;
+    }
+
+    const restored = restoreDeletedCredential(req.params.id);
+    if (restored) {
+      emitCredentialChanged(req, restored, 'restored_to_archive', {
+        fromLocation: 'recently_deleted',
+        toLocation: 'archive',
+      });
+    }
+    res.json({ success: true, action: 'restored_to_archive', credential: restored ? toMetadata(restored) : null });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// POST /credentials/purge — manual retention sweep for recently deleted credentials
+router.post('/purge', (req: Request, res: Response) => {
+  try {
+    const daysRaw = req.body?.retentionDays;
+    const retentionDays = typeof daysRaw === 'number' && Number.isFinite(daysRaw) && daysRaw > 0
+      ? Math.floor(daysRaw)
+      : 30;
+    const summary = purgeDeletedCredentials(retentionDays);
+    res.json({ success: true, retentionDays, ...summary });
+  } catch (error) {
+    res.status(500).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// POST /credentials/:id/read — decrypt, filter fields, re-encrypt to agent pubkey
+router.post('/:id/read', async (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const auth = req.auth!;
+    const requestedLocation = parseCredentialLocation(req.query.location, 'active');
+    if (!requestedLocation) {
+      res.status(400).json({ success: false, error: 'Invalid location. Expected active, archive, or recently_deleted' });
+      return;
+    }
+
+    let credentialLocation: CredentialLocation = requestedLocation;
+    let credential = getCredential(req.params.id, credentialLocation);
+    if (!credential && requestedLocation === 'active') {
+      const detectedLocation = findCredentialLocation(req.params.id);
+      if (detectedLocation) {
+        credentialLocation = detectedLocation;
+        credential = getCredential(req.params.id, credentialLocation);
+      }
+    }
+
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+    if (!canReadCredential(req, credential)) {
+      await writeDeniedCredentialAccess({
+        req,
+        credential,
+        action: 'credentials.read',
+        reasonCode: 'CREDENTIAL_SCOPE_DENIED',
+        httpStatus: 403,
+      });
+      res.status(403).json({
+        success: false,
+        error: credentialAccessErrorMessage('CREDENTIAL_SCOPE_DENIED', 'credentials.read'),
+        reasonCode: 'CREDENTIAL_SCOPE_DENIED',
+      });
+      return;
+    }
+
+    const decision = evaluateCredentialAccess({
+      tokenHash: auth.tokenHash,
+      token: auth.token,
+      credentialId: credential.id,
+      action: 'credentials.read',
+    });
+    if (!decision.allowed) {
+      await writeDeniedCredentialAccess({
+        req,
+        credential,
+        action: 'credentials.read',
+        reasonCode: decision.reasonCode,
+        httpStatus: decision.httpStatus,
+        metadata: {
+          limiterWindowMs: decision.limiterWindowMs,
+          limiterLimit: decision.limiterLimit,
+          limiterCount: decision.limiterCount,
+        },
+      });
+      res.status(decision.httpStatus).json({
+        success: false,
+        error: credentialAccessErrorMessage(decision.reasonCode, 'credentials.read'),
+        reasonCode: decision.reasonCode,
+      });
+      return;
+    }
+
+    if (!auth.token.agentPubkey) {
+      await writeDeniedCredentialAccess({
+        req,
+        credential,
+        action: 'credentials.read',
+        reasonCode: 'TOKEN_AGENT_PUBKEY_MISSING',
+        httpStatus: 400,
+      });
+      res.status(400).json({
+        success: false,
+        error: credentialAccessErrorMessage('TOKEN_AGENT_PUBKEY_MISSING', 'credentials.read'),
+        reasonCode: 'TOKEN_AGENT_PUBKEY_MISSING',
+      });
+      return;
+    }
+
+    // For oauth2 credentials, auto-refresh if expired
+    const secrets = credential.type === 'oauth2' && credentialLocation === 'active'
+      ? await readOAuth2SecretsWithRefresh(credential.id)
+      : readCredentialSecrets(credential.id, credentialLocation);
+
+    // Admin tokens should always read full credential payloads in the dashboard.
+    // Exclusion defaults are intended for delegated agent tokens.
+    const baseExclude = isAdmin(auth)
+      ? []
+      : resolveExcludeFields(auth.token.credentialAccess?.excludeFields, credential.type);
+    // For oauth2, always exclude refresh machinery from agent reads
+    const oauth2Exclude = credential.type === 'oauth2' ? OAUTH2_DEFAULT_EXCLUDE_FIELDS : [];
+    const excluded = new Set(
+      [...baseExclude, ...oauth2Exclude].map(field => normalizeScope(field)),
+    );
+    const filteredFields = secrets.filter(field => !excluded.has(normalizeScope(field.key)));
+
+    const [healthRow] = await buildCredentialHealthRows([credential], () => secrets);
+
+    const encrypted = encryptToAgentPubkey(
+      JSON.stringify({
+        id: credential.id,
+        vaultId: credential.vaultId,
+        type: credential.type,
+        fields: filteredFields,
+        health: healthRow?.health,
+      }),
+      auth.token.agentPubkey,
+    );
+
+    // Increment read usage only after successful encryption.
+    recordCredentialRead(auth.tokenHash);
+
+    const auditId = await writeCredentialAccessAudit({
+      credentialId: credential.id,
+      vaultId: credential.vaultId,
+      action: 'credentials.read',
+      allowed: true,
+      reasonCode: 'ALLOW',
+      httpStatus: 200,
+      tokenHash: auth.tokenHash,
+      agentId: auth.token.agentId,
+      requestId: req.header('x-request-id') ?? undefined,
+      actorType: isAdmin(auth) ? 'admin' : 'agent',
+      metadata: {
+        returnedFieldKeys: filteredFields.map((field) => field.key),
+      },
+    });
+    emitCredentialAccessed(req, credential, {
+      action: 'credentials.read',
+      allowed: true,
+      reasonCode: 'ALLOW',
+      httpStatus: 200,
+    });
+
+    logEvent({
+      category: 'agent',
+      action: 'credential_access_decision',
+      description: `Credential access allow: ${credential.id}`,
+      agentId: auth.token.agentId,
+      metadata: {
+        auditId,
+        credentialId: credential.id,
+        route: 'credentials.read',
+        allowed: true,
+        reasonCode: 'ALLOW',
+      },
+    });
+
+    res.json({
+      success: true,
+      credentialId: credential.id,
+      encrypted,
+    });
+  } catch (error) {
+    res.status(400).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// POST /credentials/:id/totp — generate current TOTP code
+router.post('/:id/totp', async (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const auth = req.auth!;
+
+    const credential = getCredential(req.params.id);
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+    if (!canReadCredential(req, credential)) {
+      await writeDeniedCredentialAccess({
+        req,
+        credential,
+        action: 'credentials.totp',
+        reasonCode: 'CREDENTIAL_SCOPE_DENIED',
+        httpStatus: 403,
+      });
+      res.status(403).json({
+        success: false,
+        error: credentialAccessErrorMessage('CREDENTIAL_SCOPE_DENIED', 'credentials.totp'),
+        reasonCode: 'CREDENTIAL_SCOPE_DENIED',
+      });
+      return;
+    }
+
+    // totp:read permission required (admin bypasses)
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['totp:read'])) {
+      await writeDeniedCredentialAccess({
+        req,
+        credential,
+        action: 'credentials.totp',
+        reasonCode: 'TOKEN_PERMISSION_DENIED',
+        httpStatus: 403,
+      });
+      res.status(403).json({
+        success: false,
+        error: credentialAccessErrorMessage('TOKEN_PERMISSION_DENIED', 'credentials.totp'),
+        reasonCode: 'TOKEN_PERMISSION_DENIED',
+      });
+      return;
+    }
+
+    const decision = evaluateCredentialAccess({
+      tokenHash: auth.tokenHash,
+      token: auth.token,
+      credentialId: credential.id,
+      action: 'credentials.totp',
+    });
+    if (!decision.allowed) {
+      await writeDeniedCredentialAccess({
+        req,
+        credential,
+        action: 'credentials.totp',
+        reasonCode: decision.reasonCode,
+        httpStatus: decision.httpStatus,
+        metadata: {
+          limiterWindowMs: decision.limiterWindowMs,
+          limiterLimit: decision.limiterLimit,
+          limiterCount: decision.limiterCount,
+        },
+      });
+      res.status(decision.httpStatus).json({
+        success: false,
+        error: credentialAccessErrorMessage(decision.reasonCode, 'credentials.totp'),
+        reasonCode: decision.reasonCode,
+      });
+      return;
+    }
+
+    const secrets = readCredentialSecrets(credential.id);
+    const totpField = findTotpField(secrets);
+    if (!totpField) {
+      await writeDeniedCredentialAccess({
+        req,
+        credential,
+        action: 'credentials.totp',
+        reasonCode: 'CREDENTIAL_TOTP_NOT_CONFIGURED',
+        httpStatus: 400,
+      });
+      res.status(400).json({
+        success: false,
+        error: credentialAccessErrorMessage('CREDENTIAL_TOTP_NOT_CONFIGURED', 'credentials.totp'),
+        reasonCode: 'CREDENTIAL_TOTP_NOT_CONFIGURED',
+      });
+      return;
+    }
+
+    const result = generateTOTP(totpField.value, credential.name);
+
+    const auditId = await writeCredentialAccessAudit({
+      credentialId: credential.id,
+      vaultId: credential.vaultId,
+      action: 'credentials.totp',
+      allowed: true,
+      reasonCode: 'ALLOW',
+      httpStatus: 200,
+      tokenHash: auth.tokenHash,
+      agentId: auth.token.agentId,
+      requestId: req.header('x-request-id') ?? undefined,
+      actorType: isAdmin(auth) ? 'admin' : 'agent',
+    });
+    emitCredentialAccessed(req, credential, {
+      action: 'credentials.totp',
+      allowed: true,
+      reasonCode: 'ALLOW',
+      httpStatus: 200,
+    });
+
+    logEvent({
+      category: 'agent',
+      action: 'credential_access_decision',
+      description: `Credential TOTP access allow: ${credential.id}`,
+      agentId: auth.token.agentId,
+      metadata: {
+        auditId,
+        credentialId: credential.id,
+        route: 'credentials.totp',
+        allowed: true,
+        reasonCode: 'ALLOW',
+      },
+    });
+
+    res.json({ success: true, code: result.code, remaining: result.remaining });
+  } catch (error) {
+    res.status(400).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// GET /credentials/:id/secrets — admin-only plaintext field read (for web UI)
+router.get('/:id/secrets', (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth)) {
+      res.status(403).json({ success: false, error: 'Admin access required' });
+      return;
+    }
+
+    const credential = getCredential(req.params.id);
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+
+    const fields = readCredentialSecrets(credential.id);
+
+    // If TOTP field exists, also generate current code
+    const totpField = findTotpField(fields);
+    let totp: { code: string; remaining: number } | undefined;
+    if (totpField) {
+      try {
+        totp = generateTOTP(totpField.value, credential.name);
+      } catch {
+        // Invalid TOTP secret — skip
+      }
+    }
+
+    res.json({ success: true, fields, totp });
+  } catch (error) {
+    res.status(400).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+// POST /credentials/:id/reauth — stub for re-authentication flow
+router.post('/:id/reauth', (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth)) {
+      res.status(403).json({ success: false, error: 'Admin access required' });
+      return;
+    }
+
+    const credential = getCredential(req.params.id);
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+
+    if (credential.type !== 'oauth2') {
+      res.status(400).json({ success: false, error: 'Re-auth only applies to oauth2 credentials' });
+      return;
+    }
+
+    const authorizationEndpoint = credential.meta.authorization_endpoint as string | undefined;
+    const tokenEndpoint = credential.meta.token_endpoint as string | undefined;
+
+    if (!authorizationEndpoint || !tokenEndpoint) {
+      res.status(400).json({
+        success: false,
+        error: 'OAuth2 credentials require both `authorization_endpoint` and `token_endpoint` for re-auth.',
+      });
+      return;
+    }
+
+    res.status(501).json({
+      success: false,
+      credentialId: credential.id,
+      needs_reauth: credential.meta.needs_reauth || false,
+      reauth_reason: credential.meta.reauth_reason || null,
+      authorization_endpoint: authorizationEndpoint,
+      token_endpoint: tokenEndpoint,
+      error: 'OAuth2 re-authentication flow is not implemented yet. Update credential fields manually with fresh tokens.',
+    });
+  } catch (error) {
+    res.status(400).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+export default router;