@bhooai/nexus-core 2.0.4 → 2.0.6

package/src/app/adminModule.ts

@@ -30,21 +30,42 @@
  * (endpoints return { ok: false, reason: '...' }).
  */
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile, rename, unlink } from 'node:fs/promises';
 import { createConnection } from 'node:net';
 import { join, resolve } from 'node:path';
-import type { NexusConfig } from '../config/types.js';
+import { pathToFileURL } from 'node:url';
+import type { NexusConfig, DeepPartial } from '../config/types.js';
 import type { AiProviderConfig } from '../config/types.js';
 import type { Router } from '../http/Router.js';
-import type { RequestContext } from '../http/context.js';
+import type { Middleware, RequestContext } from '../http/context.js';
 import { AiClient } from '@bhooai/nexus-ai-client';
+import { discoverUserConfigPath, frameworkDefaultConfigPath, mergeConfig } from '../config/ConfigLoader.js';
 import { readRuntimeJson, writeRuntimeJson, mergeRuntimeJson } from '../config/runtimeJson.js';
 import { readEnvFile, writeEnvEntries, writeEnvKey, deleteEnvKey } from '../config/envFile.js';
+import {
+  connectProjectInfo,
+  resolveProjectInfo,
+  listProjectInfo,
+  getProjectInfo,
+  getProjectInfoCollection,
+  upsertProjectInfo,
+  deleteProjectInfo,
+  ObjectId,
+  type ProjectInfo,
+} from '@bhooai/nexus-data';
+import { ROLE_CATALOG, findRole } from './roleCatalog.js';
+import { registerPreflightRoutes, aiHealthUrl } from './preflightModule.js';
+import { registerLintRoutes } from './lintModule.js';
+import { registerDatabaseAdminRoutes } from './databaseAdminModule.js';
+import { registerAiSchemaRoutes } from './aiSchemaModule.js';
+import { registerAiProxyRoutes } from './aiProxyModule.js';
 
 export interface AdminModuleOptions {
   name: string;
   config: NexusConfig;
   projectRoot: string;
+  /** True when a GraphQL gateway is mounted at config.graphql.path. */
+  graphqlMounted?: boolean;
 }
 
 export interface LazyDb {
@@ -59,6 +80,9 @@ export interface RequestLogEntry {
   path: string;
   status: number;
   latencyMs: number;
+  ip?: string;
+  referer?: string;
+  userAgent?: string;
 }
 
 const MAX_LOG_ENTRIES = 1000;
@@ -107,9 +131,33 @@ function tcpReachable(host: string, port: number, timeoutMs = 1200): Promise<boo
 }
 
 /** Register all admin + AI proxy routes onto the router. */
-export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, logBuffer: RequestLogBuffer, lazy: LazyDb): void {
+export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, logBuffer: RequestLogBuffer, lazy: LazyDb, guard: Middleware[] = []): void {
   const { config, projectRoot } = opts;
 
+  // Apply the auth guard (authToken + requireRole('admin')) to all /admin/* routes.
+  for (const mw of guard) router.use('/admin', mw);
+
+  // Open the shared project-info connection so /admin/config, /admin/project
+  // and the payment provider persistence can read/write the registry. Failure
+  // is non-fatal — the affected endpoints degrade gracefully.
+  try { connectProjectInfo(config.db.uri); } catch { /* Mongo may be down */ }
+
+  // ------------------------------------------------------------------
+  // /admin/supervisor — report where `nexus dev`'s control API is bound so the
+  // admin SPA can drive process control. Reads supervisor.json written by the
+  // CLI; falls back to null (the SPA then uses its 7474 default).
+  // ------------------------------------------------------------------
+  router.get('/admin/supervisor', async (ctx) => {
+    try {
+      const p = resolve(projectRoot, 'supervisor.json');
+      if (!existsSync(p)) { ctx.json({ port: null, url: null }); return; }
+      const info = JSON.parse(await readFile(p, 'utf8')) as { port?: number; url?: string };
+      ctx.json({ port: info.port ?? null, url: info.url ?? null });
+    } catch {
+      ctx.json({ port: null, url: null });
+    }
+  });
+
   // ------------------------------------------------------------------
   // /admin/health/services — TCP probes for infra services
   // ------------------------------------------------------------------
@@ -172,10 +220,21 @@ export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, lo
   });
 
   // ------------------------------------------------------------------
-  // /admin/config — read-only, redacted
+  // /admin/config — read-only, redacted (+ runtime overrides, config file, project)
   // ------------------------------------------------------------------
-  router.get('/admin/config', (ctx) => {
-    ctx.json({ config: redactConfig(config) });
+  router.get('/admin/config', async (ctx) => {
+    const project = await resolveProjectInfo(projectRoot);
+    // Prefer the stored record matched by path so a renamed project is found.
+    const stored = (await listProjectInfo().catch(() => [] as ProjectInfo[])).find((p) => p.path === project.path)
+      ?? (await getProjectInfo(project.name).catch(() => null));
+    const pkg = await readPackageJson(projectRoot);
+    const resolved = stored ?? project;
+    ctx.json({
+      runtime: await readRuntimeJson(projectRoot),
+      config: redactConfig(config),
+      file: await readUserConfigFile(projectRoot),
+      project: { ...resolved, version: pkg?.version ?? resolved.version },
+    });
   });
 
   // ------------------------------------------------------------------
@@ -192,11 +251,13 @@ export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, lo
       ctx.json({
         ok: true,
         users: users.map((u) => ({
-          id: String(u._id),
+          _id: String(u._id),
           email: u.email,
           name: u.name,
           roles: u.roles ?? ['user'],
+          emailVerified: !!u.emailVerified,
           createdAt: u.createdAt,
+          updatedAt: u.updatedAt,
         })),
       });
     } catch (err) {
@@ -231,45 +292,15 @@ export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, lo
   });
 
   // ------------------------------------------------------------------
-  // /ai/* — proxy to the Python AI server via AiClient
+  // /ai/* — proxied by registerAiProxyRoutes() below (streaming chat +
+  // provider-aware model listing). The AiClient here is reused by the AI
+  // provider management + status routes.
   // ------------------------------------------------------------------
   const aiClient = new AiClient({
     serverUrl: config.ai.serverUrl,
     timeoutMs: config.ai.timeoutMs,
   });
 
-  router.get('/ai/models', async (ctx) => {
-    try {
-      const models = await aiClient.listModels();
-      ctx.json({ ok: true, models });
-    } catch (err) {
-      ctx.json({ ok: false, reason: String((err as Error).message) });
-    }
-  });
-
-  router.post('/ai/chat', async (ctx) => {
-    const body = ctx.body as { model?: string; messages?: unknown[]; temperature?: number; max_tokens?: number; provider?: string };
-    if (!body?.messages) {
-      ctx.json({ ok: false, reason: 'messages is required' }, 400);
-      return;
-    }
-    try {
-      const providerId = body.provider ?? config.ai.defaultProvider;
-      const provider = providers.find((p) => p.id === providerId);
-      const defaultModel = provider?.defaultModel ?? config.ai.schemaModel;
-      const res = await aiClient.chat({
-        model: body.model ?? defaultModel,
-        messages: body.messages as never,
-        temperature: body.temperature,
-        max_tokens: body.max_tokens,
-        provider: providerId,
-      });
-      ctx.json({ ok: true, ...res });
-    } catch (err) {
-      ctx.json({ ok: false, reason: String((err as Error).message) });
-    }
-  });
-
   // ------------------------------------------------------------------
   // AI provider management
   // ------------------------------------------------------------------
@@ -325,15 +356,33 @@ export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, lo
       const ctrl = new AbortController();
       const timer = setTimeout(() => ctrl.abort(), 10_000);
       try {
-        const res = await fetch(`${config.ai.serverUrl.replace(/\/+$/, '')}/health`, { signal: ctrl.signal });
+        const res = await fetch(aiHealthUrl(config.ai.serverUrl, '127.0.0.1'), { signal: ctrl.signal });
         if (!res.ok) throw new Error(`HTTP ${res.status}`);
         return (await res.json()) as { status?: string; providers?: string[] };
       } finally { clearTimeout(timer); }
     });
 
+    // Probe per-provider model availability (openai / ollama) so the admin's
+    // AI Settings surface can render the auto-resolution it relies on.
+    const listModels = async (provider: 'openai' | 'ollama') => {
+      const res = await aiClient.listModels(provider);
+      const models = (res.data ?? []).map((m) => String(m.id ?? m)).slice(0, 10);
+      return { provider: res.provider, modelCount: (res.data ?? []).length, models };
+    };
+    const openai = await probe(() => listModels('openai'));
+    const ollama = await probe(() => listModels('ollama'));
+
+    const autoResolvesTo =
+      aiServer.detail && Array.isArray(aiServer.detail.providers)
+        ? (aiServer.detail.providers.includes('openai') ? 'openai' : 'ollama')
+        : 'ollama';
+
     ctx.json({
       checkedAt: new Date().toISOString(),
       aiServer,
+      openai,
+      ollama,
+      autoResolvesTo,
       defaultProvider: config.ai.defaultProvider,
       schemaModel: config.ai.schemaModel,
       serverUrl: config.ai.serverUrl,
@@ -486,6 +535,344 @@ export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, lo
       ctx.json({ ok: false, reason: String((err as Error).message) }, 500);
     }
   });
+
+  // ------------------------------------------------------------------
+  // /admin/config/file — save the human-edited config file (validated)
+  // ------------------------------------------------------------------
+  router.put('/admin/config/file', async (ctx) => {
+    const content = (ctx.body as { content?: unknown } | undefined)?.content;
+    if (typeof content !== 'string') {
+      ctx.json({ error: 'content (string) is required' }, 400);
+      return;
+    }
+    const info = await readUserConfigFile(projectRoot);
+    if (!info) {
+      ctx.json({ error: 'No user config file found (nexus.config.js / .ts)' }, 404);
+      return;
+    }
+    const original = info.content;
+    await writeTextAtomic(info.path, content);
+    try {
+      await validateUserConfigFile(info.path);
+      ctx.json({ ok: true, path: info.path, note: 'Saved to config file — restart services to apply' });
+    } catch (e) {
+      await writeTextAtomic(info.path, original);
+      ctx.json({ error: `Config file invalid — not saved: ${(e as Error).message}` }, 400);
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/roles + /admin/users/:id — role catalog + role assignment
+  // ------------------------------------------------------------------
+  router.get('/admin/roles', (ctx) => {
+    ctx.json({ roles: ROLE_CATALOG });
+  });
+
+  router.put('/admin/users/:id', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    const body = (ctx.body ?? {}) as { roles?: unknown };
+    const incoming = body.roles;
+    if (!Array.isArray(incoming) || !incoming.length || incoming.some((r) => typeof r !== 'string')) {
+      ctx.json({ error: 'roles (a non-empty string array) is required' }, 400);
+      return;
+    }
+    const nextRoles = [...new Set(incoming as string[])];
+    const unknown = nextRoles.filter((r) => !findRole(r));
+    if (unknown.length) {
+      ctx.json({ error: `unknown role(s): ${unknown.join(', ')}` }, 400);
+      return;
+    }
+
+    const id = String(ctx.params.id ?? '');
+    let oid: import('mongodb').ObjectId;
+    try { oid = new ObjectId(id); } catch { ctx.json({ error: 'invalid user id' }, 400); return; }
+    const target = await db.collection('users').findOne({ _id: oid });
+    if (!target) { ctx.json({ error: 'user not found' }, 404); return; }
+
+    const currentRoles = (target.roles ?? []) as string[];
+    const isAdmin = currentRoles.includes('admin');
+    const keepsAdmin = nextRoles.includes('admin');
+    const caller = ctx.state.user as { id?: string; roles?: string[] } | undefined;
+
+    if (isAdmin && !keepsAdmin) {
+      const adminCount = await db.collection('users').countDocuments({ roles: 'admin' });
+      if (adminCount <= 1) { ctx.json({ error: 'cannot remove the last admin from the system' }, 400); return; }
+      if (caller?.id === id) { ctx.json({ error: 'you cannot remove your own admin role' }, 400); return; }
+    }
+
+    await db.collection('users').updateOne({ _id: oid }, { $set: { roles: nextRoles } });
+    const updated = await db.collection('users').findOne({ _id: oid });
+    ctx.json({ ok: true, user: updated });
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/metrics — version / node / uptime / pid + request snapshot
+  // ------------------------------------------------------------------
+  router.get('/admin/metrics', async (ctx) => {
+    const pkg = await readPackageJson(projectRoot);
+    ctx.json({
+      metrics: {
+        http_requests_total: { values: { all: logBuffer.size } },
+      },
+      version: pkg?.version ?? null,
+      node: process.version,
+      uptime: process.uptime(),
+      pid: process.pid,
+    });
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/project — update the project registry record + package.json
+  // ------------------------------------------------------------------
+  router.put('/admin/project', async (ctx) => {
+    const body = (ctx.body ?? {}) as { name?: string; version?: string };
+    const project = await resolveProjectInfo(projectRoot);
+    const stored = (await listProjectInfo().catch(() => [] as ProjectInfo[])).find((p) => p.path === project.path)
+      ?? await getProjectInfo(project.name).catch(() => null);
+    const current = stored ?? project;
+    const next: ProjectInfo = { ...current };
+
+    if (typeof body.name === 'string' && body.name.trim() && body.name.trim() !== current.name) {
+      const newName = body.name.trim();
+      if (!/^[\w@/. -]+$/.test(newName)) { ctx.json({ error: 'project name contains unsupported characters' }, 400); return; }
+      const clash = (await listProjectInfo().catch(() => [] as ProjectInfo[])).find(
+        (p) => p.name === newName && p.path !== current.path,
+      );
+      if (clash) { ctx.json({ error: `a project named "${newName}" already exists` }, 400); return; }
+      next.name = newName;
+    }
+
+    if (typeof body.version === 'string' && body.version.trim() && body.version.trim() !== (await readPackageJson(projectRoot))?.version) {
+      const version = body.version.trim();
+      if (!/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(version)) { ctx.json({ error: `"${version}" is not a valid semver version` }, 400); return; }
+      const pkgPath = resolve(projectRoot, 'package.json');
+      let pkg: Record<string, unknown> = {};
+      try { pkg = JSON.parse(await readFile(pkgPath, 'utf8')) as Record<string, unknown>; }
+      catch { ctx.json({ error: 'package.json is missing or unreadable' }, 400); return; }
+      pkg.version = version;
+      await writeTextAtomic(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      next.version = version;
+    }
+
+    if (next.name !== current.name || next.version !== current.version) {
+      try {
+        await upsertProjectInfo(next);
+        if (next.name !== current.name) await deleteProjectInfo(current.name).catch(() => {});
+      } catch (err) {
+        ctx.json({ error: `could not persist project info: ${(err as Error).message}` }, 500);
+        return;
+      }
+    }
+    ctx.json({ ok: true, project: next });
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/plugins — plugin admin extensions (pages/slots)
+  // ------------------------------------------------------------------
+  router.get('/admin/plugins', (ctx) => {
+    // The framework does not auto-wire plugin admin extensions in
+    // createNexusApp yet; return an empty registry so the admin tab renders.
+    ctx.json({ pages: [], slots: {} });
+  });
+
+  // ------------------------------------------------------------------
+  // Payments — orders / transactions / provider status + keys
+  // ------------------------------------------------------------------
+  const paymentsCfg = config.payments ?? {} as Record<string, unknown>;
+
+  router.get('/admin/payments/orders', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ orders: [] }); return; }
+    const limit = clampInt(ctx.query.limit, 100);
+    const filter = providerFilter(ctx.query.provider);
+    try {
+      const orders = await db.collection('orders').find(filter).sort({ createdAt: -1 }).limit(limit).toArray();
+      ctx.json({
+        orders: orders.map((o) => ({
+          provider: o.provider,
+          orderId: o.orderId,
+          reference: o.reference,
+          status: o.status,
+          amount: o.amount,
+          currency: o.currency,
+          paymentId: o.paymentId,
+          createdAt: o.createdAt,
+        })),
+      });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  router.get('/admin/payments/transactions', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ transactions: [] }); return; }
+    const limit = clampInt(ctx.query.limit, 100);
+    const filter = providerFilter(ctx.query.provider);
+    try {
+      const transactions = await db.collection('transactions').find(filter).sort({ createdAt: -1 }).limit(limit).toArray();
+      ctx.json({
+        transactions: transactions.map((t) => ({
+          provider: t.provider,
+          event: t.event,
+          verified: !!t.verified,
+          orderId: t.orderId,
+          paymentId: t.paymentId,
+          amount: t.amount,
+          currency: t.currency,
+          status: t.status,
+          createdAt: t.createdAt,
+        })),
+      });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  router.get('/admin/payments/status', async (ctx) => {
+    const db = await lazy.db();
+    const results: Array<Record<string, unknown>> = [];
+    for (const name of PAYMENT_PROVIDER_NAMES) {
+      const pc = (paymentsCfg as Record<string, any>)[name] ?? {};
+      const keyFields = PAYMENT_PROVIDER_KEYS[name];
+      const entry: Record<string, unknown> = {
+        name,
+        enabled: !!pc.enabled,
+        sandbox: !!pc.sandbox,
+        configured: keyFields.every((k) => typeof pc[k] === 'string' && (pc[k] as string).length > 0),
+        live: !!db,
+        fields: keyFields.map((k) => ({
+          field: k,
+          label: PAYMENT_FIELD_LABELS[k] ?? k,
+          hasValue: typeof pc[k] === 'string' && (pc[k] as string).length > 0,
+        })),
+      };
+      entry.ok = entry.configured && !!pc.enabled;
+      entry.note = 'no public probe — create a test order to verify';
+      results.push(entry);
+    }
+    ctx.json({ checkedAt: new Date().toISOString(), providers: results });
+  });
+
+  router.put('/admin/payments/providers/:id', async (ctx) => {
+    const id = ctx.params.id ?? '';
+    if (!PAYMENT_PROVIDER_NAMES.includes(id as any)) { ctx.json({ error: `unknown provider "${id}"` }, 400); return; }
+    const body = (ctx.body ?? {}) as Record<string, unknown>;
+    const pc = (paymentsCfg as Record<string, any>)[id] ?? {};
+    if (typeof body.enabled === 'boolean') pc.enabled = body.enabled;
+    if (typeof body.sandbox === 'boolean') pc.sandbox = body.sandbox;
+    (paymentsCfg as Record<string, any>)[id] = pc;
+    const savedFields: string[] = [];
+    for (const field of PAYMENT_PROVIDER_KEYS[id as (typeof PAYMENT_PROVIDER_NAMES)[number]]) {
+      const value = body[field];
+      if (typeof value === 'string' && value.trim()) {
+        pc[field] = value.trim();
+        savedFields.push(field);
+      }
+    }
+    if (savedFields.length > 0) await writePaymentEnvKeys(projectRoot, id, pc);
+    const persistence = await persistPaymentProvider(projectRoot, id, pc);
+    ctx.json({
+      ok: true,
+      persistence,
+      savedFields,
+      provider: {
+        name: id,
+        enabled: !!pc.enabled,
+        sandbox: !!pc.sandbox,
+        configured: PAYMENT_PROVIDER_KEYS[id as (typeof PAYMENT_PROVIDER_NAMES)[number]].every((k) => typeof pc[k] === 'string' && (pc[k] as string).length > 0),
+      },
+    });
+  });
+
+  // POST /payments/order — record a test order (admin Payments test console).
+  // This is a record-only creation: it persists an order to Mongo so the
+  // Orders table reflects it. Live provider checkout is out of scope.
+  router.post('/payments/order', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    const body = (ctx.body ?? {}) as { provider?: unknown; amount?: unknown; currency?: unknown; reference?: unknown };
+    const provider = typeof body.provider === 'string' ? body.provider.trim() : '';
+    const amount = typeof body.amount === 'number' && Number.isFinite(body.amount) ? body.amount : NaN;
+    const currency = typeof body.currency === 'string' && body.currency.trim() ? body.currency.trim().toUpperCase() : (config.payments?.currency ?? 'INR');
+    const reference = typeof body.reference === 'string' && body.reference.trim() ? body.reference.trim() : `test_${Date.now()}`;
+    if (!provider || !Number.isFinite(amount)) {
+      ctx.json({ error: 'provider (string) and amount (number) are required' }, 400);
+      return;
+    }
+    const order = {
+      provider,
+      orderId: `ord_${Date.now()}`,
+      reference,
+      status: 'created',
+      amount,
+      currency,
+      createdAt: new Date().toISOString(),
+    };
+    try {
+      const res = await db.collection('orders').insertOne(order);
+      ctx.json({ ok: true, order: { ...order, _id: String(res.insertedId) } });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/requests — recent request log (from the in-memory buffer)
+  // ------------------------------------------------------------------
+  router.get('/admin/requests', (ctx) => {
+    const limit = clampInt(ctx.query.limit, 100);
+    const entries = logBuffer.tail(limit).reverse();
+    ctx.json({
+      requests: entries.map((e) => ({
+        time: e.ts,
+        method: e.method,
+        path: e.path,
+        status: e.status,
+        durationMs: e.latencyMs,
+        ip: e.ip,
+        referer: e.referer,
+        userAgent: e.userAgent,
+      })),
+    });
+  });
+
+  router.get('/admin/requests/series', (ctx) => {
+    const range = (ctx.query.range as string) ?? 'today';
+    const valid = ['today', '5d', 'week', 'month', 'year'].includes(range);
+    const r = valid ? range as RequestSeriesRange : 'today';
+    const bucketMs = r === 'today' ? 60_000 : r === '5d' || r === 'week' ? 3_600_000 : 86_400_000;
+    const now = Date.now();
+    const buckets = new Map<number, number>();
+    for (const e of logBuffer.tail(1000)) {
+      const t = Math.floor(e.ts / bucketMs) * bucketMs;
+      buckets.set(t, (buckets.get(t) ?? 0) + 1);
+    }
+    const points = [...buckets.entries()]
+      .sort((a, b) => a[0] - b[0])
+      .filter(([t]) => t >= now - rangeMs(r))
+      .map(([t, count]) => ({ t, count }));
+    ctx.json({ series: { range: r, points } });
+  });
+
+  // ------------------------------------------------------------------
+  // Wire the rest of the admin surface modules (guarded via /admin).
+  // ------------------------------------------------------------------
+  registerAiProxyRoutes(router, {
+    serverUrl: config.ai.serverUrl,
+    timeoutMs: config.ai.timeoutMs,
+    providers,
+  });
+  registerPreflightRoutes(router, config, { graphqlMounted: opts.graphqlMounted });
+  registerLintRoutes(router, config, projectRoot);
+  registerDatabaseAdminRoutes(router, lazy);
+  registerAiSchemaRoutes(router, {
+    serverUrl: config.ai.serverUrl,
+    timeoutMs: config.ai.timeoutMs,
+    model: config.ai.schemaModel,
+    providers,
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -550,24 +937,24 @@ function portOf(uri: string, fallback: number): number {
   }
 }
 
-/** Deep-clone config, masking secret-ish fields. */
+/** Deep-clone config, masking secret-ish fields (but not cookie names). */
 function redactConfig(config: NexusConfig): Record<string, unknown> {
   const clone = JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
-  redact(clone, /(secret|token|clientsecret|apikey|keyid|password|pass|refresh)/i);
+  redact(clone, /(secret|token|clientsecret|apikey|keyid|password|pass|refresh)/i, /cookiename$/i);
   return clone;
 }
 
-function redact(obj: unknown, pattern: RegExp): void {
+function redact(obj: unknown, pattern: RegExp, exclude: RegExp): void {
   if (!obj || typeof obj !== 'object') return;
   if (Array.isArray(obj)) {
-    for (const item of obj) redact(item, pattern);
+    for (const item of obj) redact(item, pattern, exclude);
     return;
   }
   for (const [k, v] of Object.entries(obj)) {
-    if (typeof v === 'string' && pattern.test(k)) {
+    if (typeof v === 'string' && pattern.test(k) && !exclude.test(k)) {
       (obj as Record<string, unknown>)[k] = '••••••••';
     } else if (v && typeof v === 'object') {
-      redact(v, pattern);
+      redact(v, pattern, exclude);
     }
   }
 }
@@ -611,3 +998,147 @@ export function createLazyDb(config: NexusConfig): LazyDb {
 }
 
 export type { RequestContext };
+
+// ---------------------------------------------------------------------------
+// Admin helper functions + payment provider metadata
+// ---------------------------------------------------------------------------
+
+export type RequestSeriesRange = 'today' | '5d' | 'week' | 'month' | 'year';
+
+function rangeMs(range: RequestSeriesRange): number {
+  const day = 86_400_000;
+  switch (range) {
+    case '5d': return 5 * day;
+    case 'week': return 7 * day;
+    case 'month': return 31 * day;
+    case 'year': return 365 * day;
+    default: return day;
+  }
+}
+
+function clampInt(v: unknown, fallback: number): number {
+  const n = typeof v === 'string' ? Number(v) : NaN;
+  return Number.isFinite(n) && n > 0 && n <= 500 ? Math.floor(n) : fallback;
+}
+
+function providerFilter(v: unknown): { provider?: string } {
+  const p = typeof v === 'string' ? v.toLowerCase().trim() : '';
+  return p ? { provider: p } : {};
+}
+
+/** Read the nearest human-edited `nexus.config.{ts,js,mjs,cjs}` (skipping the framework default). */
+async function readUserConfigFile(root: string): Promise<{ path: string; content: string } | null> {
+  const path = discoverUserConfigPath(root, frameworkDefaultConfigPath());
+  if (!path || !existsSync(path)) return null;
+  return { path, content: await readFile(path, 'utf8') };
+}
+
+/**
+ * Validate a config file by loading it exactly like the boot loader does:
+ * dynamic `import()` (ESM + TS under tsx, with a CJS interop default), then
+ * run it through the schema. Throws with a readable message when broken.
+ */
+async function validateUserConfigFile(absPath: string): Promise<void> {
+  const url = `${pathToFileURL(absPath).href}?t=${Date.now()}`;
+  const mod = (await import(url)) as Record<string, unknown>;
+  const cfg = (mod as { default?: unknown }).default ?? (mod as { config?: unknown }).config;
+  if (!cfg || typeof cfg !== 'object') {
+    throw new Error('config file must export an object (default export or named "config")');
+  }
+  mergeConfig(cfg as DeepPartial<NexusConfig>);
+}
+
+async function writeTextAtomic(path: string, content: string): Promise<void> {
+  const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tempPath, content, 'utf8');
+  try {
+    await rename(tempPath, path);
+  } catch (err) {
+    // Windows does not replace an existing file with rename(). Keep the write
+    // safe while supporting the local development platform.
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'EEXIST' && code !== 'EPERM') throw err;
+    await unlink(path).catch(() => undefined);
+    await rename(tempPath, path);
+  }
+}
+
+async function readPackageJson(root: string): Promise<{ name?: string; version?: string } | null> {
+  try {
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) as Record<string, unknown>;
+    return {
+      name: typeof pkg.name === 'string' ? pkg.name : undefined,
+      version: typeof pkg.version === 'string' ? pkg.version : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+const PAYMENT_PROVIDER_NAMES = ['razorpay', 'paypal', 'payu', 'skrill', 'payoneer'] as const;
+
+/** Credential fields that make a provider "configured". */
+const PAYMENT_PROVIDER_KEYS: Record<(typeof PAYMENT_PROVIDER_NAMES)[number], string[]> = {
+  razorpay: ['keyId', 'keySecret'],
+  paypal: ['clientId', 'clientSecret'],
+  payu: ['merchantKey', 'salt'],
+  skrill: ['merchantEmail'],
+  payoneer: ['programId', 'apiKey'],
+};
+
+/** Human-friendly labels for the credential fields shown in the admin dialog. */
+const PAYMENT_FIELD_LABELS: Record<string, string> = {
+  keyId: 'Key ID',
+  keySecret: 'Key secret',
+  clientId: 'Client ID',
+  clientSecret: 'Client secret',
+  merchantKey: 'Merchant key',
+  salt: 'Salt',
+  merchantEmail: 'Merchant email',
+  programId: 'Program ID',
+  apiKey: 'API key',
+};
+
+/** Env var name for a payment credential, e.g. razorpay.keyId → NEXUS_PAYMENTS_RAZORPAY_KEY_ID. */
+function paymentEnvKey(provider: string, field: string): string {
+  const snake = field.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+  return `NEXUS_PAYMENTS_${provider.toUpperCase()}_${snake}`;
+}
+
+/** Write credential fields for a provider into the project .env + process.env. */
+async function writePaymentEnvKeys(root: string, provider: string, pc: Record<string, unknown>): Promise<void> {
+  for (const field of PAYMENT_PROVIDER_KEYS[provider as (typeof PAYMENT_PROVIDER_NAMES)[number]]) {
+    const value = pc[field];
+    if (typeof value !== 'string' || !value) continue;
+    const envKey = paymentEnvKey(provider, field);
+    process.env[envKey] = value;
+    await writeEnvKey(root, envKey, value);
+  }
+}
+
+/** Persist a payment provider's enabled/sandbox state to runtime.json + MongoDB settings. */
+async function persistPaymentProvider(
+  root: string,
+  provider: string,
+  pc: Record<string, unknown>,
+): Promise<{ runtime: boolean; database: boolean }> {
+  const runtimeState = { enabled: !!pc.enabled, sandbox: !!pc.sandbox };
+  let runtime = false;
+  let database = false;
+  try {
+    await mergeRuntimeJson(root, { payments: { [provider]: runtimeState } });
+    runtime = true;
+  } catch { /* surfaced via persistence flags */ }
+  try {
+    const project = await resolveProjectInfo(root);
+    const coll = await getProjectInfoCollection();
+    const result = await coll.updateOne(
+      { name: project.name },
+      { $set: { [`settings.payments.${provider}`]: runtimeState } },
+      { upsert: false },
+    );
+    if (result.matchedCount === 0) throw new Error(`project "${project.name}" was not found in nexus_projects`);
+    database = true;
+  } catch { /* surfaced via persistence flags */ }
+  return { runtime, database };
+}