tr-plugin-auth 0.0.0-stage → 1.0.0

package/src/secrets-store.mjs

@@ -0,0 +1,756 @@
+/** Optional secret administration; encrypted storage lives in the portable gateway. */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import os from 'os';
+import YAML from 'yaml';
+import { authLedger, appendAuthMetadata } from './metadata-state.mjs';
+import { resolveSecretsPath, resolveAuditPath, resolveUsagePath, secretsPassword, readTrEnvFilePassword, isPlainJsonStore, loadSecretsSync, saveSecretsSync, loadSecrets, saveSecrets, validateSecretsBuffer, replaceSecretsBufferAtomic, ensureMeta, appendAudit, META_KEY } from './secrets-gateway.mjs';
+export * from './secrets-gateway.mjs';
+
+/**
+ * Parse repos field. A credential may be bound to zero (developer/tooling),
+ * one, or several repos; uniqueness per repo is not required.
+ *
+ * @param {string|string[]|null|undefined} v
+ * @param {object} [_opts] - accepted for compatibility; there is no limit
+ * @returns {string[]}
+ */
+export function normalizeReposBinding(v, _opts = {}) {
+  let list = [];
+  if (Array.isArray(v)) {
+    list = [...new Set(v.map(String).map((s) => s.trim()).filter(Boolean))];
+  } else if (typeof v === 'string') {
+    list = [
+      ...new Set(
+        v
+          .split(/[,;\s]+/)
+          .map((s) => s.trim())
+          .filter(Boolean),
+      ),
+    ];
+  }
+  return list;
+}
+
+/**
+ * Multi-repo binding is allowed, so this is never a violation. Kept because
+ * callers still read the field.
+ */
+export function isMultiRepoViolation(_meta = {}) {
+  return false;
+}
+
+/** Lowercase, de-duplicated tag list from an array or comma/space separated string. */
+export function normalizeTags(v) {
+  const raw = Array.isArray(v) ? v : String(v ?? '').split(/[,;\s]+/);
+  return [...new Set(raw.map((t) => String(t).trim().toLowerCase()).filter(Boolean))];
+}
+
+/**
+ * Normalize / merge secret metadata (never stores values).
+ * @param {object} prev
+ * @param {object} patch
+ */
+export function mergeSecretMeta(prev = {}, patch = {}) {
+  const next = { ...prev };
+  const assign = (field, transform) => {
+    if (patch[field] !== undefined) {
+      next[field] = transform ? transform(patch[field]) : patch[field];
+    }
+  };
+  assign('scope', (v) => (v === 'project' ? 'project' : 'global'));
+  assign('provider', (v) => (v ? String(v).toLowerCase() : null));
+  assign('label', (v) => (v == null ? null : String(v)));
+  // empty = Developer secrets
+  assign('repos', (v) => normalizeReposBinding(v));
+  assign('tags', normalizeTags);
+  assign('subscription_tier', (v) => (v == null || v === '' ? null : String(v)));
+  assign('monthly_cost_usd', (v) => (v == null || v === '' ? null : Number(v)));
+  assign('monthly_cap_usd', (v) => (v == null || v === '' ? null : Number(v)));
+  assign('api_docs_url', (v) => (v == null || v === '' ? null : String(v)));
+  assign('console_url', (v) => (v == null || v === '' ? null : String(v)));
+  assign('pricing_url', (v) => (v == null || v === '' ? null : String(v)));
+  assign('schema_notes', (v) => (v == null || v === '' ? null : String(v)));
+  assign('auth_scheme', (v) => (v == null || v === '' ? null : String(v)));
+  assign('rotate_every_days', (v) => {
+    if (v == null || v === '' || v === false) return null;
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  });
+  assign('auto_rotate', (v) => !!v);
+  assign('notes', (v) => (v == null || v === '' ? null : String(v)));
+  assign('project_path', (v) => (v == null || v === '' ? null : String(v)));
+  assign('headscale_url', (v) => (v == null || v === '' ? null : String(v)));
+  // Command that prints the headscale server log. Watch mode needs it because
+  // headscale exposes no pending-registration API -- a device waiting to be
+  // approved is visible only in the log. Kept as config so no host is ever
+  // named in code.
+  assign('headscale_log_command', (v) => (v == null || v === '' ? null : String(v)));
+  // Live provider account / usage / subscription tracking (provider-account-sync)
+  assign('tracking_exempt', (v) => !!v);
+  assign('tracking_status', (v) => {
+    if (v == null || v === '') return null;
+    const s = String(v).toLowerCase();
+    return ['ok', 'partial', 'error', 'exempt', 'never'].includes(s) ? s : 'error';
+  });
+  assign('tracking_error', (v) => (v == null || v === '' ? null : String(v)));
+  assign('tracking_synced_at', (v) => (v == null || v === '' ? null : String(v)));
+  assign('tracking_probe', (v) => (v == null || v === '' ? null : String(v)));
+  assign('tracking_account', (v) => (v == null ? null : v));
+  assign('tracking_usage', (v) => (v == null ? null : v));
+  assign('tracking_subscription', (v) => (v == null ? null : v));
+  assign('account_api', (v) => (v == null ? null : !!v));
+  assign('usage_api', (v) => (v == null ? null : !!v));
+  assign('subscription_api', (v) => (v == null ? null : !!v));
+  assign('key_valid', (v) => (v == null ? null : !!v));
+  // Operator waiver: intentional shared credential (rare — prefer unique keys per app)
+  assign('shared_value_ok', (v) => !!v);
+  if (patch.updated_at) next.updated_at = patch.updated_at;
+  if (patch.rotated_at) next.rotated_at = patch.rotated_at;
+  if (patch.created_at && !next.created_at) next.created_at = patch.created_at;
+  return next;
+}
+
+/**
+ * Compute next rotation due ISO date from meta.
+ */
+export function nextRotateDue(meta = {}) {
+  if (!meta.rotate_every_days) return null;
+  const base = meta.rotated_at || meta.updated_at || meta.created_at;
+  if (!base) return null;
+  const t = new Date(base).getTime() + meta.rotate_every_days * 86400000;
+  if (!Number.isFinite(t)) return null;
+  return new Date(t).toISOString();
+}
+
+/** Canonical app label for repo binding (empty = developer/global). */
+export function appLabelForSecret(row = {}) {
+  if (row.repo) return String(row.repo);
+  if (Array.isArray(row.repos) && row.repos.length === 1) return String(row.repos[0]);
+  if (Array.isArray(row.repos) && row.repos.length > 1) return row.repos.join('+');
+  return 'developer';
+}
+
+/**
+ * Full value fingerprint (never truncated — used for equality).
+ * @param {string} value
+ */
+export function secretValueFingerprint(value) {
+  if (value == null || value === '') return null;
+  return crypto.createHash('sha256').update(String(value)).digest('hex');
+}
+
+/**
+ * Build shared-value groups from rows that already have fingerprint_full + set.
+ * Same credential material under multiple key names / apps must be an ERROR so
+ * each app can get its own rotated key.
+ *
+ * @param {Array<object>} rows - secret meta rows (with fingerprint_full)
+ * @returns {{ groups: object[], byKey: Map<string, object> }}
+ */
+export function buildSharedValueIndex(rows = []) {
+  const byFp = new Map();
+  for (const row of rows) {
+    if (!row?.set || !row.fingerprint_full) continue;
+    // Skip pure internal passwords that are intentionally shared (e.g. same JWT across?)
+    // No — still flag; operator can mark shared_value_ok.
+    if (!byFp.has(row.fingerprint_full)) byFp.set(row.fingerprint_full, []);
+    byFp.get(row.fingerprint_full).push(row);
+  }
+
+  const groups = [];
+  const byKey = new Map();
+
+  for (const [fp, members] of byFp) {
+    if (members.length < 2) continue;
+    const apps = [...new Set(members.map((m) => appLabelForSecret(m)))].sort();
+    const keys = members.map((m) => m.key).sort();
+    const providers = [...new Set(members.map((m) => m.provider).filter(Boolean))];
+    const multiApp = apps.length > 1;
+    const multiKey = keys.length > 1;
+    // Error unless every member is operator-waived
+    const allOk = members.every((m) => m.shared_value_ok === true);
+    // Sharing a value across keys or repos is allowed; it is reported for
+    // information only and never counts as unhealthy.
+    void allOk;
+    const severity = 'info';
+    const error = multiApp
+      ? `Shared value across [${apps.join(', ')}] as keys [${keys.join(', ')}] (allowed).`
+      : `Same value stored under ${keys.length} secret names [${keys.join(', ')}] (allowed).`;
+
+    const group = {
+      fingerprint: fp.slice(0, 12),
+      fingerprint_full: fp,
+      count: members.length,
+      apps,
+      multi_app: multiApp,
+      multi_key: multiKey,
+      keys,
+      providers,
+      severity,
+      error,
+      members: members.map((m) => ({
+        key: m.key,
+        repo: m.repo || null,
+        repos: m.repos || [],
+        app: appLabelForSecret(m),
+        provider: m.provider || null,
+        masked: m.masked || null,
+        shared_value_ok: !!m.shared_value_ok,
+      })),
+    };
+    groups.push(group);
+    for (const m of members) {
+      byKey.set(m.key, {
+        shared_value: true,
+        shared_with: members
+          .filter((o) => o.key !== m.key)
+          .map((o) => ({
+            key: o.key,
+            app: appLabelForSecret(o),
+            repo: o.repo || null,
+            provider: o.provider || null,
+          })),
+        shared_apps: apps,
+        shared_value_error: error,
+        shared_value_severity: severity,
+        shared_fingerprint: fp.slice(0, 12),
+      });
+    }
+  }
+
+  groups.sort((a, b) => b.count - a.count || a.fingerprint.localeCompare(b.fingerprint));
+  return { groups, byKey };
+}
+
+/**
+ * List secret keys with rich metadata only (no values).
+ * Annotates shared-value groups (same credential material under multiple keys/apps).
+ */
+export async function listSecretsMeta(brainDir) {
+  const { getProvider, providerForKeyName } = await import('./provider-catalog.mjs');
+  const secrets = ensureMeta(await loadSecrets(brainDir));
+  const meta = secrets[META_KEY].keys || {};
+  const usageByKey = summarizeUsageByKey(brainDir, { days: 30 });
+  const keys = Object.keys(secrets).filter((k) => k !== META_KEY);
+  const rows = keys.map((key) => {
+    const m = meta[key] || {};
+    const val = secrets[key];
+    const providerId = m.provider || providerForKeyName(key)?.id || null;
+    const catalog = providerId ? getProvider(providerId) : providerForKeyName(key);
+    const due = nextRotateDue(m);
+    const now = Date.now();
+    const rotation_overdue = due ? new Date(due).getTime() < now : false;
+    const usage = usageByKey.by_key[key] || {
+      events: 0,
+      cost_usd: 0,
+      input_tokens: 0,
+      output_tokens: 0,
+    };
+    const repos = Array.isArray(m.repos) ? m.repos.filter(Boolean) : [];
+    const fpFull =
+      typeof val === 'string' && val.length ? secretValueFingerprint(val) : null;
+    return {
+      key,
+      set: val !== undefined && val !== null && val !== '',
+      length: typeof val === 'string' ? val.length : val != null ? String(val).length : 0,
+      fingerprint: fpFull ? fpFull.slice(0, 12) : null,
+      fingerprint_full: fpFull,
+      masked:
+        typeof val === 'string' && val.length > 8
+          ? `${val.slice(0, 4)}…${val.slice(-4)}`
+          : val
+            ? '••••••••'
+            : null,
+      scope: m.scope || 'global',
+      provider: providerId,
+      provider_name: catalog?.name || providerId,
+      label: m.label || null,
+      repos,
+      repo: repos.length === 1 ? repos[0] : null,
+      multi_repo_error: false,
+      binding_error: null,
+      tags: Array.isArray(m.tags) ? m.tags : [],
+      project_path: m.project_path || null,
+      subscription_tier: m.subscription_tier || null,
+      monthly_cost_usd: m.monthly_cost_usd ?? null,
+      monthly_cap_usd: m.monthly_cap_usd ?? catalog?.default_monthly_cap_usd ?? null,
+      api_docs_url: m.api_docs_url || catalog?.docs_url || null,
+      console_url: m.console_url || catalog?.console_url || null,
+      pricing_url: m.pricing_url || catalog?.pricing_url || null,
+      schema: catalog?.schema || null,
+      schema_notes: m.schema_notes || catalog?.schema?.notes || null,
+      auth_scheme: m.auth_scheme || catalog?.schema?.auth || null,
+      rotate_every_days: m.rotate_every_days ?? null,
+      auto_rotate: !!m.auto_rotate,
+      next_rotate_due: due,
+      rotation_overdue,
+      notes: m.notes || null,
+      created_at: m.created_at || null,
+      updated_at: m.updated_at || null,
+      rotated_at: m.rotated_at || null,
+      headscale_url: m.headscale_url || null,
+      headscale_log_command: m.headscale_log_command || null,
+      usage_30d: usage,
+      tiers: catalog?.tiers || [],
+      // Provider account/usage tracking (must be ok or exempt — else error)
+      tracking_exempt: !!m.tracking_exempt,
+      tracking_status: m.tracking_status || (m.tracking_exempt ? 'exempt' : null),
+      tracking_error: m.tracking_error || null,
+      tracking_synced_at: m.tracking_synced_at || null,
+      tracking_probe: m.tracking_probe || null,
+      tracking_account: m.tracking_account || null,
+      tracking_usage: m.tracking_usage || null,
+      tracking_subscription: m.tracking_subscription || null,
+      account_api: m.account_api ?? null,
+      usage_api: m.usage_api ?? null,
+      subscription_api: m.subscription_api ?? null,
+      key_valid: m.key_valid ?? null,
+      shared_value_ok: !!m.shared_value_ok,
+    };
+  });
+
+  const { byKey: sharedByKey } = buildSharedValueIndex(rows);
+  return rows.map((row) => {
+    const shared = sharedByKey.get(row.key);
+    const { fingerprint_full: _full, ...publicRow } = row;
+    if (!shared) {
+      return {
+        ...publicRow,
+        shared_value: false,
+        shared_with: [],
+        shared_apps: [],
+        shared_value_error: null,
+        shared_value_severity: null,
+      };
+    }
+    return {
+      ...publicRow,
+      shared_value: true,
+      shared_with: shared.shared_with,
+      shared_apps: shared.shared_apps,
+      shared_value_error: shared.shared_value_error,
+      shared_value_severity: shared.shared_value_severity,
+      shared_fingerprint: shared.shared_fingerprint,
+    };
+  });
+}
+
+/**
+ * Report of credential values reused across secret names / apps.
+ * healthy=false when any unwaived share exists.
+ */
+export async function getSharedValueHealth(brainDir) {
+  const secrets = ensureMeta(await loadSecrets(brainDir));
+  const meta = secrets[META_KEY].keys || {};
+  const rows = [];
+  for (const key of Object.keys(secrets)) {
+    if (key === META_KEY) continue;
+    const val = secrets[key];
+    if (val === undefined || val === null || val === '') continue;
+    const m = meta[key] || {};
+    const repos = Array.isArray(m.repos) ? m.repos.filter(Boolean) : [];
+    rows.push({
+      key,
+      set: true,
+      provider: m.provider || null,
+      repos,
+      repo: repos.length === 1 ? repos[0] : null,
+      fingerprint_full: secretValueFingerprint(String(val)),
+      masked:
+        typeof val === 'string' && val.length > 8
+          ? `${val.slice(0, 4)}…${val.slice(-4)}`
+          : '••••••••',
+      shared_value_ok: !!m.shared_value_ok,
+    });
+  }
+  const { groups } = buildSharedValueIndex(rows);
+  const errorGroups = groups.filter((g) => g.severity === 'error');
+  const multiAppGroups = errorGroups.filter((g) => g.multi_app);
+  return {
+    healthy: errorGroups.length === 0,
+    groups,
+    error_groups: errorGroups.length,
+    multi_app_groups: multiAppGroups.length,
+    shared_keys: errorGroups.reduce((n, g) => n + g.count, 0),
+    message:
+      errorGroups.length === 0
+        ? 'No shared credential values across secret names/apps'
+        : `SHARED KEY ERROR: ${errorGroups.length} credential value(s) reused across secret names/apps — issue unique keys per app`,
+    errors: errorGroups.map((g) => ({
+      fingerprint: g.fingerprint,
+      apps: g.apps,
+      keys: g.keys,
+      error: g.error,
+    })),
+  };
+}
+
+/**
+ * Full catalog payload for UI: keys + providers + usage totals.
+ */
+export async function getSecretsCatalog(brainDir) {
+  const { listProviders } = await import('./provider-catalog.mjs');
+  const keys = await listSecretsMeta(brainDir);
+  const usage30 = summarizeUsage(brainDir, { days: 30 });
+  const usage7 = summarizeUsage(brainDir, { days: 7 });
+  const budget = loadBudgetConfig(brainDir);
+  const monthlyPlanned = keys.reduce((s, k) => s + (Number(k.monthly_cost_usd) || 0), 0);
+  const overdue = keys.filter((k) => k.rotation_overdue);
+  const multiRepoViolations = [];
+  const developerKeys = keys.filter((k) => !k.repos?.length);
+  const productKeys = keys.filter((k) => k.repos?.length >= 1);
+  const byProvider = {};
+  for (const k of keys) {
+    const p = k.provider || 'unknown';
+    if (!byProvider[p]) byProvider[p] = { provider: p, keys: 0, cost_30d: 0, monthly_cost: 0 };
+    byProvider[p].keys++;
+    byProvider[p].cost_30d += k.usage_30d?.cost_usd || 0;
+    byProvider[p].monthly_cost += Number(k.monthly_cost_usd) || 0;
+  }
+  const setKeys = keys.filter((k) => k.set);
+  const trackingOk = setKeys.filter((k) => k.tracking_status === 'ok');
+  const trackingExempt = setKeys.filter((k) => k.tracking_status === 'exempt' || k.tracking_exempt);
+  const trackingErrors = setKeys.filter(
+    (k) => k.tracking_status !== 'ok' && k.tracking_status !== 'exempt' && !k.tracking_exempt,
+  );
+  const sharedKeys = setKeys.filter((k) => k.shared_value && k.shared_value_severity === 'error');
+  const sharedApps = setKeys.filter(
+    (k) => k.shared_value && k.shared_value_severity === 'error' && (k.shared_apps?.length || 0) > 1,
+  );
+  // Build unique shared groups from key annotations
+  const seenFp = new Set();
+  const sharedGroups = [];
+  for (const k of sharedKeys) {
+    const fp = k.shared_fingerprint || k.fingerprint;
+    if (!fp || seenFp.has(fp)) continue;
+    seenFp.add(fp);
+    sharedGroups.push({
+      fingerprint: fp,
+      apps: k.shared_apps || [],
+      keys: [k.key, ...(k.shared_with || []).map((s) => s.key)],
+      error: k.shared_value_error,
+    });
+  }
+  return {
+    keys,
+    providers: listProviders(),
+    summary: {
+      total_keys: keys.length,
+      providers_active: Object.keys(byProvider).length,
+      monthly_subscription_usd: monthlyPlanned,
+      multi_repo_violations: multiRepoViolations.length,
+      developer_keys: developerKeys.length,
+      product_keys: productKeys.length,
+      usage_7d: usage7,
+      usage_30d: usage30,
+      rotation_overdue: overdue.length,
+      budget: budget.config,
+      tracking_healthy: trackingErrors.length === 0,
+      tracking_ok: trackingOk.length,
+      tracking_exempt: trackingExempt.length,
+      tracking_errors: trackingErrors.length,
+      tracking_error_keys: trackingErrors.map((k) => ({
+        key: k.key,
+        provider: k.provider,
+        tracking_status: k.tracking_status || 'never',
+        error: k.tracking_error || 'Never synced — run secret account-sync',
+      })),
+      // Same credential material under multiple key names / repos
+      shared_value_healthy: sharedKeys.length === 0,
+      shared_value_keys: sharedKeys.length,
+      shared_value_multi_app_keys: sharedApps.length,
+      shared_value_groups: sharedGroups.length,
+      shared_value_errors: sharedGroups,
+    },
+    by_provider: Object.values(byProvider).sort((a, b) => b.cost_30d - a.cost_30d),
+    store: resolveSecretsPath(brainDir),
+  };
+}
+
+/**
+ * Update metadata only (no value change).
+ */
+export async function updateSecretMeta(brainDir, key, patch = {}, opts = {}) {
+  const secrets = ensureMeta(await loadSecrets(brainDir));
+  if (!(key in secrets) || key === META_KEY) {
+    throw new Error(`Secret not found: ${key}`);
+  }
+  const prev = secrets[META_KEY].keys[key] || {};
+  secrets[META_KEY].keys[key] = mergeSecretMeta(prev, {
+    ...patch,
+    updated_at: new Date().toISOString(),
+    created_at: prev.created_at || new Date().toISOString(),
+  });
+  await saveSecrets(brainDir, secrets);
+  appendAudit(brainDir, {
+    action: 'meta',
+    key,
+    actor: opts.actor || 'cli',
+    fields: Object.keys(patch),
+  });
+  return listSecretsMeta(brainDir).then((rows) => rows.find((r) => r.key === key));
+}
+
+/**
+ * Secrets due for rotation (auto_rotate or overdue).
+ */
+export async function listRotationDue(brainDir, { autoOnly = false } = {}) {
+  const keys = await listSecretsMeta(brainDir);
+  return keys.filter((k) => {
+    if (!k.next_rotate_due) return false;
+    if (!k.rotation_overdue) return false;
+    if (autoOnly && !k.auto_rotate) return false;
+    return true;
+  });
+}
+
+/**
+ * Set a secret. Value never returned in audit.
+ */
+export async function setSecret(brainDir, key, value, opts = {}) {
+  if (!key || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(key)) {
+    throw new Error('Invalid secret key. Use letters, numbers, _ . - (start with a letter).');
+  }
+  if (key === META_KEY) throw new Error('Reserved key name');
+  if (value === undefined || value === null || value === '') {
+    throw new Error('Secret value must be non-empty');
+  }
+
+  const secrets = ensureMeta(await loadSecrets(brainDir));
+  const prev = secrets[META_KEY].keys[key] || {};
+  const now = new Date().toISOString();
+  secrets[key] = String(value);
+  secrets[META_KEY].keys[key] = mergeSecretMeta(prev, {
+    scope: opts.scope || prev.scope || 'global',
+    provider: opts.provider || prev.provider || null,
+    repos: opts.repos !== undefined ? opts.repos : prev.repos,
+    tags: opts.tags !== undefined ? opts.tags : prev.tags,
+    subscription_tier: opts.subscription_tier !== undefined ? opts.subscription_tier : prev.subscription_tier,
+    monthly_cost_usd: opts.monthly_cost_usd !== undefined ? opts.monthly_cost_usd : prev.monthly_cost_usd,
+    monthly_cap_usd: opts.monthly_cap_usd !== undefined ? opts.monthly_cap_usd : prev.monthly_cap_usd,
+    api_docs_url: opts.api_docs_url !== undefined ? opts.api_docs_url : prev.api_docs_url,
+    headscale_url: opts.headscale_url !== undefined ? opts.headscale_url : prev.headscale_url,
+    headscale_log_command:
+      opts.headscale_log_command !== undefined ? opts.headscale_log_command : prev.headscale_log_command,
+    rotate_every_days: opts.rotate_every_days !== undefined ? opts.rotate_every_days : prev.rotate_every_days,
+    auto_rotate: opts.auto_rotate !== undefined ? opts.auto_rotate : prev.auto_rotate,
+    notes: opts.notes !== undefined ? opts.notes : prev.notes,
+    project_path: opts.project_path !== undefined ? opts.project_path : prev.project_path,
+    label: opts.label !== undefined ? opts.label : prev.label,
+    created_at: prev.created_at || now,
+    updated_at: now,
+  });
+  await saveSecrets(brainDir, secrets);
+  appendAudit(brainDir, {
+    action: 'set',
+    key,
+    scope: secrets[META_KEY].keys[key].scope,
+    provider: secrets[META_KEY].keys[key].provider,
+    actor: opts.actor || 'cli',
+    project_id: opts.project_id || null,
+  });
+
+  return { key, set: true };
+}
+
+/**
+ * Get a secret value (CLI only — do not inject into surfaces).
+ */
+export async function getSecret(brainDir, key, opts = {}) {
+  const secrets = await loadSecrets(brainDir);
+  if (!(key in secrets) || key === META_KEY) {
+    return { found: false, key };
+  }
+  appendAudit(brainDir, {
+    action: opts.action || 'get',
+    key,
+    actor: opts.actor || 'cli',
+    project_id: opts.project_id || null,
+  });
+  return { found: true, key, value: secrets[key] };
+}
+
+/**
+ * Delete a secret.
+ */
+export async function deleteSecret(brainDir, key, opts = {}) {
+  const secrets = ensureMeta(await loadSecrets(brainDir));
+  if (!(key in secrets) || key === META_KEY) {
+    return { found: false, key };
+  }
+  delete secrets[key];
+  if (secrets[META_KEY].keys) delete secrets[META_KEY].keys[key];
+  await saveSecrets(brainDir, secrets);
+  appendAudit(brainDir, { action: 'delete', key, actor: opts.actor || 'cli' });
+  return { found: true, key, deleted: true };
+}
+
+/**
+ * Rotate: set new value, mark rotated_at.
+ */
+export async function rotateSecret(brainDir, key, newValue, opts = {}) {
+  if (!newValue) throw new Error('New value required for rotate');
+  const secrets = ensureMeta(await loadSecrets(brainDir));
+  if (!(key in secrets) || key === META_KEY) {
+    throw new Error(`Secret not found: ${key}`);
+  }
+  secrets[key] = String(newValue);
+  const prev = secrets[META_KEY].keys[key] || {};
+  const now = new Date().toISOString();
+  secrets[META_KEY].keys[key] = mergeSecretMeta(prev, {
+    scope: opts.scope || prev.scope || 'global',
+    provider: opts.provider || prev.provider || null,
+    updated_at: now,
+    rotated_at: now,
+  });
+  await saveSecrets(brainDir, secrets);
+  appendAudit(brainDir, { action: 'rotate', key, actor: opts.actor || 'cli' });
+  return { key, rotated: true, next_rotate_due: nextRotateDue(secrets[META_KEY].keys[key]) };
+}
+
+/**
+ * Read last N audit lines (no values).
+ */
+export function readSecretAudit(brainDir, { limit = 50 } = {}) {
+  const auditPath = resolveAuditPath(brainDir);
+  return authLedger(auditPath).slice(-limit);
+}
+
+/**
+ * Record a usage/cost event (no secrets).
+ */
+export function recordUsage(brainDir, event) {
+  const usagePath = resolveUsagePath(brainDir);
+  fs.mkdirSync(path.dirname(usagePath), { recursive: true });
+  const row = {
+    ts: new Date().toISOString(),
+    provider: event.provider || 'unknown',
+    model: event.model || null,
+    input_tokens: event.input_tokens || 0,
+    output_tokens: event.output_tokens || 0,
+    cost_usd: event.cost_usd ?? null,
+    source: event.source || 'cli',
+    key_ref: event.key_ref || null, // secret *name* only, never value
+  };
+  appendAuthMetadata(usagePath, row);
+  return row;
+}
+
+/**
+ * Load budget.yml if present.
+ */
+export function loadBudgetConfig(brainDir) {
+  const candidates = [
+    path.join(brainDir, 'config', 'budget.yml'),
+    path.join(process.cwd(), 'config', 'budget.yml'),
+  ];
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      return { path: p, config: YAML.parse(fs.readFileSync(p, 'utf8')) || {} };
+    } catch {
+      return { path: p, config: {}, error: 'parse failed' };
+    }
+  }
+  return {
+    path: null,
+    config: { daily_cap_usd: 5, weekly_cap_usd: 25 },
+  };
+}
+
+/** @deprecated alias */
+export const loadBudget = loadBudgetConfig;
+
+/**
+ * Sum usage.jsonl costs for last N days.
+ */
+export function summarizeUsage(brainDir, { days = 1 } = {}) {
+  const usagePath = resolveUsagePath(brainDir);
+  const cutoff = Date.now() - days * 86400000;
+  let events = 0;
+  let cost = 0;
+  let input = 0;
+  let output = 0;
+  for (const row of authLedger(usagePath)) {
+      const t = new Date(row.ts).getTime();
+      if (t < cutoff) continue;
+      events++;
+      cost += Number(row.cost_usd) || 0;
+      input += Number(row.input_tokens) || 0;
+      output += Number(row.output_tokens) || 0;
+  }
+  return { events, cost_usd: cost, input_tokens: input, output_tokens: output, days };
+}
+
+/**
+ * Usage rollup by key_ref and provider for last N days.
+ */
+export function summarizeUsageByKey(brainDir, { days = 30 } = {}) {
+  const usagePath = resolveUsagePath(brainDir);
+  const by_key = {};
+  const by_provider = {};
+  const cutoff = Date.now() - days * 86400000;
+  for (const row of authLedger(usagePath)) {
+      const t = new Date(row.ts).getTime();
+      if (t < cutoff) continue;
+      const kref = row.key_ref || '_unattributed';
+      const prov = row.provider || 'unknown';
+      if (!by_key[kref]) {
+        by_key[kref] = { events: 0, cost_usd: 0, input_tokens: 0, output_tokens: 0 };
+      }
+      by_key[kref].events++;
+      by_key[kref].cost_usd += Number(row.cost_usd) || 0;
+      by_key[kref].input_tokens += Number(row.input_tokens) || 0;
+      by_key[kref].output_tokens += Number(row.output_tokens) || 0;
+      if (!by_provider[prov]) {
+        by_provider[prov] = { events: 0, cost_usd: 0, input_tokens: 0, output_tokens: 0 };
+      }
+      by_provider[prov].events++;
+      by_provider[prov].cost_usd += Number(row.cost_usd) || 0;
+      by_provider[prov].input_tokens += Number(row.input_tokens) || 0;
+      by_provider[prov].output_tokens += Number(row.output_tokens) || 0;
+  }
+  return { by_key, by_provider, days };
+}
+
+/**
+ * Recent usage rows (no secrets), newest last.
+ */
+export function listUsageEvents(brainDir, { limit = 100, key_ref = null, days = 30 } = {}) {
+  const usagePath = resolveUsagePath(brainDir);
+  const cutoff = Date.now() - days * 86400000;
+  const rows = [];
+  for (const row of authLedger(usagePath)) {
+      const t = new Date(row.ts).getTime();
+      if (t < cutoff) continue;
+      if (key_ref && row.key_ref !== key_ref) continue;
+      rows.push(row);
+  }
+  return rows.slice(-limit);
+}
+
+/**
+ * True if any secret value appears in text (for surface/openwiki conformance).
+ */
+export async function textContainsSecrets(brainDir, text) {
+  if (!text) return { leak: false, keys: [] };
+  const secrets = await loadSecrets(brainDir);
+  const leaked = [];
+  for (const [key, val] of Object.entries(secrets)) {
+    if (key === META_KEY) continue;
+    if (typeof val === 'string' && val.length >= 8 && text.includes(val)) {
+      leaked.push(key);
+    }
+  }
+  return { leak: leaked.length > 0, keys: leaked };
+}
+
+/**
+ * Resolve brain dir for secrets (global or project).
+ */
+export function defaultBrainDir() {
+  return process.env.TR_SECRETS_BRAIN || process.env._TR_TEST_BRAIN_DIR || process.env.TR_BRAIN ||
+    path.join(process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR || path.join(os.homedir(), '.agent'), 'skills', 'total-recall');
+}