auramaxx 0.0.1

package/server/routes/credentials.ts

@@ -0,0 +1,1782 @@
+import { randomBytes } from 'crypto';
+import { NextFunction, Request, Response, Router } from 'express';
+import {
+  archiveCredential,
+  createCredential,
+  deleteArchivedCredential,
+  deleteCredential,
+  duplicateCredential,
+  findCredentialLocation,
+  getCredential,
+  isValidCredentialId,
+  listCredentials,
+  purgeDeletedCredentials,
+  readCredentialSecrets,
+  restoreArchivedCredential,
+  restoreDeletedCredential,
+  updateCredential,
+  type CredentialLocation,
+} from '../lib/credentials';
+import { getErrorMessage } from '../lib/error';
+import { buildPermissionDenied, 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 { resolveDontAskAgainDefault } from '../lib/dont-ask-again-policy';
+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 { createHotWallet, deleteHotWallet, exportHotWallet } from '../lib/hot';
+import { evaluateCredentialAccess } from '../lib/credential-access-policy';
+import { writeCredentialAccessAudit } from '../lib/credential-access-audit';
+import { prisma } from '../lib/db';
+import { getDefault } from '../lib/defaults';
+import { computeGpgFingerprint, computeSshFingerprint } from '../lib/key-fingerprint';
+import { events } from '../lib/events';
+import { createHumanActionNotification } from '../lib/notifications';
+import { hashSecret } from '../lib/crypto';
+import { buildApproveUrl } from '../lib/approval-link';
+import {
+  buildCredentialHealthRows,
+  summarizeCredentialHealthFlags,
+} from '../lib/credential-health';
+import {
+  NOTE_CONTENT_KEY,
+  getCredentialFieldValue,
+  normalizeCredentialFieldsForType,
+} from '../../shared/credential-field-schema';
+
+const router = Router();
+
+const VALID_CREDENTIAL_TYPES = new Set<CredentialType>([
+  'login',
+  'card',
+  'note',
+  'plain_note',
+  'hot_wallet',
+  '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']);
+
+const OAUTH2_REAUTH_STATE_TTL_MS = 10 * 60 * 1000;
+const oauth2ReauthState = new Map<string, { credentialId: string; redirectUri: string; expiresAt: number }>();
+
+router.use(requireWalletAuth);
+
+router.param('id', (req: Request, res: Response, next: NextFunction, id: string) => {
+  if (!isValidCredentialId(id)) {
+    res.status(400).json({ success: false, error: 'Invalid credential id format' });
+    return;
+  }
+  next();
+});
+
+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 findSensitiveFieldValue(fields: CredentialField[], key: string): string {
+  const field = fields.find((entry) => entry.key === key);
+  return typeof field?.value === 'string' ? field.value : '';
+}
+
+function upsertSensitiveField(fields: CredentialField[], key: string, value: string): CredentialField[] {
+  const next = [...fields];
+  const index = next.findIndex((entry) => entry.key === key);
+  const normalized: CredentialField = { key, value, type: 'secret', sensitive: true };
+  if (index >= 0) next[index] = normalized;
+  else next.push(normalized);
+  return next;
+}
+
+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 normalizePlainNoteFields(fields: CredentialField[]): CredentialField[] {
+  return fields.map((field) => ({ ...field, sensitive: false, type: 'text' }));
+}
+
+function resolvePlainNoteContent(
+  meta: Record<string, unknown>,
+  fallbackFields: CredentialField[] = [],
+): string {
+  const contentFromMeta = typeof meta[NOTE_CONTENT_KEY] === 'string' ? meta[NOTE_CONTENT_KEY] : '';
+  if (contentFromMeta.trim()) return contentFromMeta;
+
+  // Legacy plain-note support: older payloads may still send/store `value`.
+  const legacyMetaValue = typeof meta.value === 'string' ? meta.value : '';
+  if (legacyMetaValue.trim()) return legacyMetaValue;
+
+  const normalizedFieldValue = getCredentialFieldValue('plain_note', fallbackFields, NOTE_CONTENT_KEY) || '';
+  return normalizedFieldValue.trim() ? normalizedFieldValue : '';
+}
+
+function normalizePlainNoteMeta(
+  meta: Record<string, unknown>,
+  fallbackFields: CredentialField[] = [],
+): Record<string, unknown> {
+  const normalizedMeta = { ...meta };
+  const content = resolvePlainNoteContent(normalizedMeta, fallbackFields);
+  normalizedMeta[NOTE_CONTENT_KEY] = content;
+  delete normalizedMeta.value;
+  delete normalizedMeta.key;
+  return normalizedMeta;
+}
+
+function plainNoteFieldsFromMeta(
+  meta: Record<string, unknown>,
+  fallbackFields: CredentialField[] = [],
+): CredentialField[] {
+  const content = resolvePlainNoteContent(meta, fallbackFields);
+  return [
+    { key: NOTE_CONTENT_KEY, value: content, type: 'text', sensitive: false },
+  ];
+}
+
+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'
+    | 'duplicated',
+  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 === 'DENY_EXCLUDED_FIELD') return 'Excluded credential fields require human approval';
+  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' | 'DENY_EXCLUDED_FIELD';
+  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('/', async (req: Request, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['secret:write'])) {
+      res.status(403).json({ success: false, ...buildPermissionDenied('secret:write permission required', ['secret:write'], auth.token.permissions) });
+      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 rawFieldsInitial = normalizeCredentialFieldsForType(type, parseFields(req.body?.fields));
+    const rawFields = type === 'plain_note' ? normalizePlainNoteFields(rawFieldsInitial) : rawFieldsInitial;
+    const sensitiveFieldsInitial = normalizeCredentialFieldsForType(type, parseFields(req.body?.sensitiveFields));
+    const sensitiveFields = type === 'plain_note' ? [] : sensitiveFieldsInitial;
+    let fieldsToEncrypt = sensitiveFields.length > 0
+      ? sensitiveFields
+      : rawFields.filter(field => field.sensitive);
+    let finalMeta = mergeNonSensitiveFieldsIntoMeta(normalizedMeta, rawFields);
+    let provisionedHotWalletAddress: string | null = null;
+
+    if (type === 'plain_note') {
+      const normalizedPlainNoteMeta = normalizePlainNoteMeta(finalMeta, rawFields);
+      if (!resolvePlainNoteContent(normalizedPlainNoteMeta, rawFields)) {
+        res.status(400).json({ success: false, error: 'plain_note requires non-empty content field' });
+        return;
+      }
+      finalMeta = normalizedPlainNoteMeta;
+    }
+
+    if (!isAdmin(auth) && type === 'hot_wallet') {
+      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, ...buildPermissionDenied('Credential write scope denied', ['secret:write'], auth.token.permissions) });
+        return;
+      }
+    }
+
+    if (type === 'hot_wallet') {
+      if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['wallet:create:hot'])) {
+        res.status(403).json({ success: false, ...buildPermissionDenied('wallet:create:hot permission required', ['wallet:create:hot'], auth.token.permissions) });
+        return;
+      }
+
+      const chainFromMeta = typeof finalMeta.chain === 'string' ? finalMeta.chain.trim().toLowerCase() : '';
+      const chain = chainFromMeta || 'base';
+      try {
+        const hotWallet = await createHotWallet({
+          tokenHash: auth.tokenHash,
+          chain,
+          name,
+          coldWalletId: vaultId === 'primary' ? undefined : vaultId,
+        });
+        provisionedHotWalletAddress = hotWallet.address;
+        const exported = await exportHotWallet(hotWallet.address);
+
+        fieldsToEncrypt = [{
+          key: 'private_key',
+          value: exported.privateKey,
+          type: 'secret',
+          sensitive: true,
+        }];
+
+        finalMeta = normalizeMeta({
+          ...finalMeta,
+          address: hotWallet.address,
+          chain: hotWallet.chain || chain,
+          walletLink: {
+            version: 1,
+            walletAddress: hotWallet.address,
+            chain: hotWallet.chain || chain,
+            tier: 'hot',
+            source: 'created',
+            ...(hotWallet.name ? { label: hotWallet.name } : {}),
+          },
+        });
+      } catch (error) {
+        if (provisionedHotWalletAddress) {
+          await deleteHotWallet(provisionedHotWalletAddress).catch(() => {});
+        }
+        throw error;
+      }
+    }
+
+    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) && type !== 'hot_wallet') {
+      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, ...buildPermissionDenied('Credential write scope denied', ['secret:write'], auth.token.permissions) });
+        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;
+    }
+
+    let created: CredentialFile;
+    try {
+      created = createCredential(vaultId, type as CredentialType, name, finalMeta, fieldsToEncrypt);
+    } catch (error) {
+      if (provisionedHotWalletAddress) {
+        await deleteHotWallet(provisionedHotWalletAddress).catch(() => {});
+      }
+      throw error;
+    }
+
+    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, ...buildPermissionDenied('secret:read permission required', ['secret:read'], auth.token.permissions) });
+      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, ...buildPermissionDenied('secret:read permission required', ['secret:read'], auth.token.permissions) });
+      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, ...buildPermissionDenied('secret:read permission required', ['secret:read'], auth.token.permissions) });
+      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, ...buildPermissionDenied('secret:read permission required', ['secret:read'], auth.token.permissions) });
+      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, ...buildPermissionDenied('secret:read permission required', ['secret:read'], auth.token.permissions) });
+      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, ...buildPermissionDenied('Credential read scope denied', ['secret:read'], req.auth!.token.permissions) });
+      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, ...buildPermissionDenied('Credential write scope denied', ['secret:write'], req.auth!.token.permissions) });
+      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 parsedFields = normalizeCredentialFieldsForType(credential.type, parseFields(req.body?.fields));
+    const fields = credential.type === 'plain_note' ? normalizePlainNoteFields(parsedFields) : parsedFields;
+    if (fields.length > 0 || updatedMeta) {
+      const baseMeta = updatedMeta || { ...credential.meta };
+      updatedMeta = mergeNonSensitiveFieldsIntoMeta(baseMeta, fields);
+    }
+
+    if (credential.type === 'plain_note' && updatedMeta) {
+      const existingPlainNoteSecrets = readCredentialSecrets(credential.id);
+      const plainNoteFallbackFields = [...existingPlainNoteSecrets, ...fields];
+      updatedMeta = normalizePlainNoteMeta(updatedMeta, plainNoteFallbackFields);
+      if (!resolvePlainNoteContent(updatedMeta, plainNoteFallbackFields)) {
+        res.status(400).json({ success: false, error: 'plain_note requires non-empty content field' });
+        return;
+      }
+    }
+
+    let sensitiveFields: CredentialField[] | undefined;
+    const hasSensitiveInput = req.body && Object.prototype.hasOwnProperty.call(req.body, 'sensitiveFields');
+    if (credential.type === 'plain_note') {
+      sensitiveFields = [];
+    } else if (hasSensitiveInput) {
+      sensitiveFields = normalizeCredentialFieldsForType(credential.type, 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, ...buildPermissionDenied('Credential write scope denied', ['secret:write'], req.auth!.token.permissions) });
+      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, ...buildPermissionDenied('Credential write scope denied', ['secret:write'], req.auth!.token.permissions) });
+      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/:id/duplicate — duplicate an active credential
+router.post('/:id/duplicate', (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth) && !hasAnyPermission(auth.token.permissions, ['secret:write'])) {
+      res.status(403).json({ success: false, ...buildPermissionDenied('secret:write permission required', ['secret:write'], auth.token.permissions) });
+      return;
+    }
+
+    const source = getCredential(req.params.id, 'active');
+    if (!source) {
+      res.status(404).json({ success: false, error: 'Credential not found in active location' });
+      return;
+    }
+
+    if (!canWriteCredential(req, source)) {
+      res.status(403).json({ success: false, ...buildPermissionDenied('Credential write scope denied', ['secret:write'], auth.token.permissions) });
+      return;
+    }
+
+    const { name, vaultId } = req.body || {};
+    const newCred = duplicateCredential(req.params.id, {
+      name: typeof name === 'string' ? name : undefined,
+      vaultId: typeof vaultId === 'string' ? vaultId : undefined,
+    });
+
+    emitCredentialChanged(req, newCred, 'duplicated');
+    res.json({ success: true, credential: toMetadata(newCred) });
+  } 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.
+    // For plain notes, we still read encrypted fields as a fallback for older data.
+    const rawSecrets = credential.type === 'oauth2' && credentialLocation === 'active'
+      ? await readOAuth2SecretsWithRefresh(credential.id)
+      : readCredentialSecrets(credential.id, credentialLocation);
+    const secrets = credential.type === 'plain_note'
+      ? plainNoteFieldsFromMeta(credential.meta, rawSecrets)
+      : normalizeCredentialFieldsForType(credential.type, rawSecrets);
+
+    // 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);
+    const baseExcludedNormalized = new Set(baseExclude.map(field => normalizeScope(field)));
+    const requestedExcludedFields = isAdmin(auth)
+      ? []
+      : Array.from(new Set(
+          secrets
+            .map((field) => field.key)
+            .filter((fieldKey) => baseExcludedNormalized.has(normalizeScope(fieldKey))),
+        ));
+    if (requestedExcludedFields.length > 0) {
+      const approvalTtl = await getDefault<number>('ttl.action', 60);
+      const approvalSummaryBase = `${auth.token.agentId || 'agent'} requests excluded fields (${requestedExcludedFields.join(', ')}) from credential "${credential.name}"`;
+      const approvalSummary = approvalSummaryBase.length > 500
+        ? `${approvalSummaryBase.slice(0, 497)}...`
+        : approvalSummaryBase;
+      const secret = randomBytes(32).toString('hex');
+      const secretHash = hashSecret(secret);
+      const requestedExcludedNormalized = new Set(requestedExcludedFields.map((field) => normalizeScope(field)));
+      const escalationExcludeFields = Array.from(
+        new Set(
+          baseExclude
+            .map((field) => normalizeScope(field))
+            .filter((field) => !requestedExcludedNormalized.has(field)),
+        ),
+      );
+      const dontAskAgainDecision = resolveDontAskAgainDefault(requestedExcludedFields);
+      const request = await prisma.humanAction.create({
+        data: {
+          type: 'auth',
+          fromTier: 'system',
+          toAddress: null,
+          amount: null,
+          chain: 'base',
+          status: 'pending',
+          metadata: JSON.stringify({
+            agentId: auth.token.agentId,
+            limit: 0,
+            limits: { fund: 0, send: 0, swap: 0 },
+            permissions: ['secret:read'],
+            ttl: approvalTtl,
+            credentialAccess: {
+              read: [credential.id],
+              write: [],
+              excludeFields: escalationExcludeFields,
+              maxReads: 1,
+              ttl: approvalTtl,
+            },
+            pubkey: auth.token.agentPubkey,
+            secretHash,
+            summary: approvalSummary,
+            escalationReason: 'DENY_EXCLUDED_FIELD',
+            credentialId: credential.id,
+            credentialName: credential.name,
+            vaultId: credential.vaultId,
+            requestedFields: requestedExcludedFields,
+            policyContext: {
+              readScopes: auth.token.credentialAccess?.read || [],
+              tokenExcludeFields: auth.token.credentialAccess?.excludeFields ?? null,
+              effectiveExcludeFields: baseExclude,
+              credentialType: credential.type,
+              dontAskAgainDefaultOn: dontAskAgainDecision.defaultOn,
+              dontAskAgainReason: dontAskAgainDecision.reason,
+            },
+          }),
+        },
+      });
+      await createHumanActionNotification(request);
+      events.actionCreated({
+        id: request.id,
+        type: 'agent_access',
+        source: `agent:${auth.token.agentId || 'agent'}`,
+        summary: approvalSummary,
+        expiresAt: null,
+        metadata: {
+          agentId: auth.token.agentId,
+          credentialId: credential.id,
+          credentialName: credential.name,
+          requestedFields: requestedExcludedFields,
+          effectiveExcludeFields: baseExclude,
+          reasonCode: 'DENY_EXCLUDED_FIELD',
+        },
+      });
+      await writeDeniedCredentialAccess({
+        req,
+        credential,
+        action: 'credentials.read',
+        reasonCode: 'DENY_EXCLUDED_FIELD',
+        httpStatus: 403,
+        metadata: {
+          humanActionId: request.id,
+          requestedFields: requestedExcludedFields,
+          effectiveExcludeFields: baseExclude,
+          dontAskAgainDefaultOn: dontAskAgainDecision.defaultOn,
+          dontAskAgainReason: dontAskAgainDecision.reason,
+        },
+      });
+      logEvent({
+        category: 'agent',
+        action: 'credential_access_decision',
+        description: `Credential access denied (excluded fields): ${credential.id}`,
+        agentId: auth.token.agentId,
+        metadata: {
+          credentialId: credential.id,
+          route: 'credentials.read',
+          allowed: false,
+          reasonCode: 'DENY_EXCLUDED_FIELD',
+          requestedFields: requestedExcludedFields,
+          humanActionId: request.id,
+        },
+      });
+      const dashboardBase = `http://localhost:${process.env.DASHBOARD_PORT || '4747'}`;
+      res.status(403).json({
+        success: false,
+        error: credentialAccessErrorMessage('DENY_EXCLUDED_FIELD', 'credentials.read'),
+        reasonCode: 'DENY_EXCLUDED_FIELD',
+        escalated: true,
+        requiresHumanApproval: true,
+        requestId: request.id,
+        secret,
+        approveUrl: buildApproveUrl(dashboardBase, request.id),
+        message: 'Action escalated — waiting for human approval',
+        credential: {
+          id: credential.id,
+          name: credential.name,
+          vaultId: credential.vaultId,
+        },
+        requestedFields: requestedExcludedFields,
+        effectiveExcludeFields: baseExclude,
+        dontAskAgainDefaultOn: dontAskAgainDecision.defaultOn,
+        dontAskAgainReason: dontAskAgainDecision.reason,
+      });
+      return;
+    }
+    // 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,
+    });
+
+    const secretSurface = req.header('x-secret-surface') as 'inject_secret' | 'get_secret' | undefined;
+    if (secretSurface) {
+      events.secretAccessed({
+        credentialId: credential.id,
+        credentialName: req.header('x-credential-name') || credential.name,
+        vaultId: credential.vaultId,
+        surface: secretSurface,
+        envVar: req.header('x-secret-envvar') || undefined,
+        agentId: auth.token.agentId,
+        tokenHash: auth.tokenHash,
+      });
+    }
+
+    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, ...buildPermissionDenied('Admin access required', ['admin:*'], auth.token.permissions) });
+      return;
+    }
+
+    const credential = getCredential(req.params.id);
+    if (!credential) {
+      res.status(404).json({ success: false, error: 'Credential not found' });
+      return;
+    }
+
+    const fields = credential.type === 'plain_note'
+      ? plainNoteFieldsFromMeta(credential.meta, readCredentialSecrets(credential.id))
+      : 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 — oauth2 re-auth start/complete flow
+router.post('/:id/reauth', async (req: Request<{ id: string }>, res: Response) => {
+  try {
+    const auth = req.auth!;
+    if (!isAdmin(auth)) {
+      res.status(403).json({ success: false, ...buildPermissionDenied('Admin access required', ['admin:*'], auth.token.permissions) });
+      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;
+    }
+
+    const secrets = readCredentialSecrets(credential.id);
+    const clientId = findSensitiveFieldValue(secrets, 'client_id');
+    const clientSecret = findSensitiveFieldValue(secrets, 'client_secret');
+    const existingRefreshToken = findSensitiveFieldValue(secrets, 'refresh_token');
+
+    if (!clientId) {
+      res.status(400).json({ success: false, error: 'oauth2 reauth requires sensitive field client_id' });
+      return;
+    }
+
+    const body = (req.body || {}) as { code?: string; state?: string; redirect_uri?: string };
+    const code = typeof body.code === 'string' ? body.code.trim() : '';
+
+    if (!code) {
+      const redirectUri = (typeof body.redirect_uri === 'string' && body.redirect_uri.trim())
+        || (credential.meta.redirect_uri as string | undefined)
+        || 'urn:ietf:wg:oauth:2.0:oob';
+      const state = randomBytes(16).toString('hex');
+      oauth2ReauthState.set(state, {
+        credentialId: credential.id,
+        redirectUri,
+        expiresAt: Date.now() + OAUTH2_REAUTH_STATE_TTL_MS,
+      });
+
+      const params = new URLSearchParams({
+        response_type: 'code',
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        state,
+      });
+      const scopes = typeof credential.meta.scopes === 'string' ? credential.meta.scopes.trim() : '';
+      if (scopes) params.set('scope', scopes);
+
+      res.json({
+        success: true,
+        phase: 'authorization_required',
+        message: 'Open provider consent URL, then submit returned authorization code to complete re-auth.',
+        credentialId: credential.id,
+        authorization_url: `${authorizationEndpoint}${authorizationEndpoint.includes('?') ? '&' : '?'}${params.toString()}`,
+        state,
+      });
+      return;
+    }
+
+    const providedState = typeof body.state === 'string' ? body.state.trim() : '';
+    if (!providedState) {
+      res.status(400).json({ success: false, error: 'state is required when completing oauth2 reauth' });
+      return;
+    }
+
+    const stateRecord = oauth2ReauthState.get(providedState);
+    if (!stateRecord || stateRecord.credentialId !== credential.id || stateRecord.expiresAt < Date.now()) {
+      res.status(400).json({ success: false, error: 'Invalid or expired reauth state. Start re-auth again.' });
+      return;
+    }
+
+    const redirectUri = stateRecord.redirectUri;
+    oauth2ReauthState.delete(providedState);
+
+    const authMethod = String(credential.meta.auth_method || 'client_secret_post');
+    const tokenBody = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: redirectUri,
+    });
+
+    const headers: Record<string, string> = { 'content-type': 'application/x-www-form-urlencoded' };
+    if (authMethod === 'client_secret_post') {
+      tokenBody.set('client_id', clientId);
+      tokenBody.set('client_secret', clientSecret);
+    } else {
+      const basic = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
+      headers.authorization = `Basic ${basic}`;
+      tokenBody.set('client_id', clientId);
+    }
+
+    const tokenRes = await fetch(tokenEndpoint, {
+      method: 'POST',
+      headers,
+      body: tokenBody.toString(),
+    });
+
+    let tokenPayload: Record<string, unknown> = {};
+    try {
+      tokenPayload = await tokenRes.json() as Record<string, unknown>;
+    } catch {
+      tokenPayload = {};
+    }
+
+    if (!tokenRes.ok) {
+      const reason = String(tokenPayload.error_description || tokenPayload.error || `OAuth2 re-auth failed (${tokenRes.status})`);
+      updateCredential(credential.id, {
+        meta: {
+          ...credential.meta,
+          needs_reauth: true,
+          reauth_reason: reason,
+        },
+      });
+      res.status(400).json({ success: false, error: reason, phase: 'failed' });
+      return;
+    }
+
+    const accessToken = String(tokenPayload.access_token || '').trim();
+    if (!accessToken) {
+      res.status(400).json({ success: false, error: 'Provider response missing access_token' });
+      return;
+    }
+
+    const refreshToken = String(tokenPayload.refresh_token || existingRefreshToken || '').trim();
+    const expiresIn = Number(tokenPayload.expires_in);
+    const nextExpiresAt = Number.isFinite(expiresIn) && expiresIn > 0
+      ? Math.floor(Date.now() / 1000) + expiresIn
+      : Number(credential.meta.expires_at || Math.floor(Date.now() / 1000) + 3600);
+
+    let nextSecrets = upsertSensitiveField(secrets, 'access_token', accessToken);
+    nextSecrets = upsertSensitiveField(nextSecrets, 'refresh_token', refreshToken);
+
+    updateCredential(credential.id, {
+      meta: {
+        ...credential.meta,
+        expires_at: nextExpiresAt,
+        needs_reauth: false,
+        reauth_reason: null,
+        last_refreshed: new Date().toISOString(),
+      },
+      sensitiveFields: nextSecrets,
+    });
+
+    res.json({
+      success: true,
+      phase: 'completed',
+      credentialId: credential.id,
+      message: 'OAuth2 credential re-authenticated successfully.',
+      expires_at: nextExpiresAt,
+    });
+  } catch (error) {
+    res.status(400).json({ success: false, error: getErrorMessage(error) });
+  }
+});
+
+export default router;