@bhooai/nexus-core 2.0.5 → 2.0.7

package/src/app/databaseAdminModule.ts

@@ -0,0 +1,222 @@
+import type { Router } from '../index.js';
+
+/**
+ * Admin routes for MongoDB database / collection administration.
+ *
+ * The admin app uses these to create, rename and drop databases and
+ * collections, and to preview documents. Collections can be created with a
+ * `$jsonSchema` validator (used by the AI schema generator).
+ *
+ * Routes (guarded by the caller's /admin middleware):
+ *   GET    /admin/databases                       → { databases: [{ name, sizeOnDisk, collections: [{ name, count }] }] }
+ *   POST   /admin/databases                       → { name } → create
+ *   DELETE /admin/databases/:db                   → drop database
+ *   POST   /admin/databases/:db/collections       → { name, jsonSchema? } → create
+ *   PUT    /admin/databases/:db/collections/:name → { newName? | validator? } → rename / collMod
+ *   DELETE /admin/databases/:db/collections/:name → drop collection
+ *   GET    /admin/databases/:db/collections/:name/docs → { count, docs } (preview, max 10)
+ */
+
+/** Resolves the connected Mongo Db (or null when Mongo is unreachable). */
+export interface LazyDb {
+  db(): Promise<import('mongodb').Db | null>;
+}
+
+const DOC_PREVIEW_LIMIT = 10;
+
+/** Ugly but real: dropping a db's only collection deletes the whole database. */
+const BOOTSTRAP_COLLECTION = '_nexus_bootstrap';
+
+/** Databases managed by MongoDB itself — hidden from the admin surface. */
+const SYSTEM_DATABASES = new Set(['admin', 'local', 'config']);
+
+export function registerDatabaseAdminRoutes(router: Router, lazy: LazyDb): void {
+  router.get('/admin/databases', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    try {
+      const list = await db.client.db().admin().listDatabases();
+      const databases = [];
+      for (const d of list.databases) {
+        if (!d.name || SYSTEM_DATABASES.has(d.name)) continue;
+        const mongoDb = db.client.db(d.name);
+        const raw = await mongoDb.listCollections().toArray();
+        const collections = [];
+        for (const c of raw) {
+          if (c.name.startsWith(BOOTSTRAP_COLLECTION)) continue;
+          let count = 0;
+          try { count = await mongoDb.collection(c.name).countDocuments({}, { maxTimeMS: 5000 }); } catch { /* stats unavailable */ }
+          collections.push({ name: c.name, count });
+        }
+        databases.push({ name: d.name, sizeOnDisk: d.sizeOnDisk ?? 0, collections });
+      }
+      ctx.json({ databases });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  router.post('/admin/databases', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    const name = assertDbName((ctx.body as { name?: unknown } | undefined)?.name, ctx);
+    if (!name) return;
+    try {
+      // Mongo creates a database lazily on first write. Keep a hidden bootstrap
+      // collection so the database exists immediately; internal collections are
+      // filtered out of the listing.
+      await db.client.db(name).createCollection(BOOTSTRAP_COLLECTION);
+      ctx.json({ ok: true, name });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  router.delete('/admin/databases/:db', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    const name = assertDbName(ctx.params.db, ctx);
+    if (!name) return;
+    try {
+      await db.client.db(name).dropDatabase();
+      ctx.json({ ok: true, dropped: name });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  router.post('/admin/databases/:db/collections', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    const dbName = assertDbName(ctx.params.db, ctx);
+    if (!dbName) return;
+    const body = (ctx.body ?? {}) as { name?: unknown; jsonSchema?: unknown };
+    const name = assertCollectionName(body.name, ctx);
+    if (!name) return;
+    const validator = parseJsonSchema(body.jsonSchema, ctx);
+    if (ctx.res.writableEnded) return;
+    try {
+      const mongoDb = db.client.db(dbName);
+      if (validator) {
+        await mongoDb.createCollection(name, {
+          validator: { $jsonSchema: validator },
+          validationLevel: 'strict',
+          validationAction: 'error',
+        });
+      } else {
+        await mongoDb.createCollection(name);
+      }
+      ctx.json({ ok: true, db: dbName, collection: name, validator: validator ? { $jsonSchema: validator } : null });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  router.put('/admin/databases/:db/collections/:name', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    const dbName = assertDbName(ctx.params.db, ctx);
+    if (!dbName) return;
+    const name = assertCollectionName(ctx.params.name, ctx);
+    if (!name) return;
+    const body = (ctx.body ?? {}) as { newName?: unknown; validator?: unknown };
+    const mongoDb = db.client.db(dbName);
+    const changed: string[] = [];
+    try {
+      if (body.newName !== undefined) {
+        const newName = assertCollectionName(body.newName, ctx);
+        if (!newName) return;
+        if (newName !== name) {
+          await mongoDb.collection(name).rename(newName);
+          changed.push(`renamed to ${newName}`);
+        }
+      }
+      if (body.validator !== undefined) {
+        const validator = parseJsonSchema(body.validator, ctx);
+        if (ctx.res.writableEnded) return;
+        await mongoDb.command({
+          collMod: changed.length ? String(body.newName) : name,
+          validator: { $jsonSchema: validator },
+          validationLevel: 'strict',
+        });
+        changed.push('validator updated');
+      }
+      if (!changed.length) {
+        ctx.json({ error: 'nothing to modify — send newName and/or validator' }, 400);
+        return;
+      }
+      ctx.json({ ok: true, db: dbName, collection: name, changed });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  router.delete('/admin/databases/:db/collections/:name', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    const dbName = assertDbName(ctx.params.db, ctx);
+    if (!dbName) return;
+    const name = assertCollectionName(ctx.params.name, ctx);
+    if (!name) return;
+    try {
+      await db.client.db(dbName).dropCollection(name);
+      ctx.json({ ok: true, dropped: { db: dbName, collection: name } });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+
+  router.get('/admin/databases/:db/collections/:name/docs', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) { ctx.json({ error: 'MongoDB not reachable' }, 503); return; }
+    const dbName = assertDbName(ctx.params.db, ctx);
+    if (!dbName) return;
+    const name = assertCollectionName(ctx.params.name, ctx);
+    if (!name) return;
+    try {
+      const coll = db.client.db(dbName).collection(name);
+      const count = await coll.countDocuments();
+      const docs = await coll.find({}).limit(DOC_PREVIEW_LIMIT).toArray();
+      ctx.json({ db: dbName, collection: name, count, docs });
+    } catch (err) {
+      ctx.json({ error: (err as Error).message }, 500);
+    }
+  });
+}
+
+function assertDbName(v: unknown, ctx: { json(data: unknown, status?: number): void; res: { writableEnded: boolean } }): string | null {
+  const name = typeof v === 'string' ? v.trim() : '';
+  if (!name || name.length > 63) { ctx.json({ error: 'database name is required (max 63 chars)' }, 400); return null; }
+  if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(name) || name.includes('..')) {
+    ctx.json({ error: `invalid database name: ${name}` }, 400);
+    return null;
+  }
+  return name;
+}
+
+function assertCollectionName(v: unknown, ctx: { json(data: unknown, status?: number): void; res: { writableEnded: boolean } }): string | null {
+  const name = typeof v === 'string' ? v.trim() : '';
+  if (!name || name.length > 255) { ctx.json({ error: 'collection name is required (max 255 chars)' }, 400); return null; }
+  if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(name) || name.startsWith('system.')) {
+    ctx.json({ error: `invalid collection name: ${name}` }, 400);
+    return null;
+  }
+  return name;
+}
+
+function parseJsonSchema(v: unknown, ctx: { json(data: unknown, status?: number): void; res: { writableEnded: boolean } }): Record<string, unknown> | null {
+  if (v === undefined || v === null) return null;
+  if (typeof v === 'string') {
+    try { v = JSON.parse(v); } catch { ctx.json({ error: 'jsonSchema is not valid JSON' }, 400); return null; }
+  }
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+    ctx.json({ error: 'jsonSchema must be an object' }, 400);
+    return null;
+  }
+  const schema = v as Record<string, unknown>;
+  if (schema.bsonType !== 'object' || typeof schema.properties !== 'object' || schema.properties === null) {
+    ctx.json({ error: 'jsonSchema must have bsonType: "object" and a properties object' }, 400);
+    return null;
+  }
+  return schema;
+}

package/src/app/index.ts

@@ -13,3 +13,5 @@ export * from './Seeder.js';
 export * from './Storage.js';
 export * from './maintenance.js';
 export * from './adminModule.js';
+export * from './authModule.js';
+export * from './userModel.js';

package/src/app/lintModule.ts

@@ -0,0 +1,102 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Router, NexusConfig } from '../index.js';
+
+/**
+ * Config / .env linter proxy.
+ *
+ * Node reads the raw files (auth + file access boundary) and posts the text to
+ * the Python AI server, which computes the lint report. This keeps linting
+ * logic in Python and file/secret ownership in Node. When the engine is not
+ * reachable a graceful `engine_offline` report is returned (the admin UI
+ * renders that state).
+ *
+ *   POST /admin/lint/env      { env }  -> report
+ *   POST /admin/lint/config            -> report
+ */
+
+export interface LintCheck {
+  key: string;
+  severity: 'error' | 'warning' | 'info' | 'ok';
+  kind: string;
+  message: string;
+  errorCategory?: string;
+}
+
+export interface LintReport {
+  ranAt: string;
+  engineOk?: boolean;
+  summary: { error: number; warning: number; info: number; ok: number };
+  checks: LintCheck[];
+}
+
+function envPathOf(root: string, name: string): string {
+  const safe = /^\.env(?:\.\w+)*$/.test(name ?? '.env') ? name : '.env';
+  return join(root, safe);
+}
+
+/** Register `POST /admin/lint/env` + `/admin/lint/config`. */
+export function registerLintRoutes(router: Router, config: NexusConfig, root: string): void {
+  const serverUrlRaw = config.ai?.serverUrl ?? 'http://localhost:8000';
+  const serverUrl = serverUrlRaw.replace(/\/+$/, '');
+  const timeoutMs = config.ai?.timeoutMs ?? 60_000;
+
+  const toPython = async (path: string, body: Record<string, unknown>): Promise<LintReport> => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${serverUrl}${path}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      if (!res.ok) throw new Error(`AI server returned HTTP ${res.status}`);
+      return (await res.json()) as LintReport;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  const failed = (): LintReport => ({
+    ranAt: new Date().toISOString(),
+    engineOk: false,
+    summary: { error: 1, warning: 0, info: 0, ok: 0 },
+    checks: [
+      {
+        key: 'linter-engine',
+        severity: 'error',
+        kind: 'engine',
+        errorCategory: 'engine_offline',
+        message: 'Python diagnostics engine offline — start it with "python main.py" or "nexus dev"',
+      },
+    ],
+  });
+
+  router.post('/admin/lint/env', async (ctx) => {
+    const body = (ctx.body ?? {}) as { env?: unknown };
+    const envName = typeof body.env === 'string' && body.env.trim() ? body.env.trim() : '.env';
+    try {
+      const envPath = envPathOf(root, envName);
+      const envText = existsSync(envPath) ? await readFile(envPath, 'utf8') : '';
+      try {
+        ctx.json(await toPython('/lint/env', { envText }));
+      } catch {
+        ctx.json(failed());
+      }
+    } catch (err) {
+      ctx.json({ error: (err as Error).message, summary: { error: 0, warning: 0, info: 0, ok: 0 }, checks: [] }, 400);
+    }
+  });
+
+  router.post('/admin/lint/config', async (ctx) => {
+    const runtimePath = join(root, 'nexus.runtime.json');
+    const content = existsSync(runtimePath) ? await readFile(runtimePath, 'utf8') : '{}';
+    try {
+      ctx.json(await toPython('/lint/config', { content }));
+    } catch {
+      ctx.json(failed());
+    }
+  });
+}

package/src/app/preflightModule.ts

@@ -0,0 +1,259 @@
+import { createConnection } from 'node:net';
+import type { Router, NexusConfig } from '../index.js';
+
+/**
+ * Preflight diagnostics — native Node connectivity/latency probes.
+ *
+ * The admin Overview's "run checks" button hits `POST /admin/preflight`.
+ * Node performs the probes itself (fetch + net), so the report does not depend
+ * on the Python engine. Target addresses are derived from config but always
+ * normalized to a connectable loopback address — binding on 0.0.0.0 is legal
+ * for a listener but invalid as a connect target.
+ */
+
+export interface PreflightTarget {
+  name: string;
+  kind: 'http' | 'tcp';
+  url?: string;
+  host?: string;
+  port?: number;
+  timeout?: number;
+}
+
+export interface PreflightCheck {
+  name: string;
+  kind: string;
+  ok: boolean;
+  latencyMs?: number;
+  status?: number | null;
+  host?: string;
+  port?: number;
+  url?: string;
+  error?: string | null;
+  errorCategory?: string | null;
+}
+
+export interface PreflightReport {
+  ranAt: string;
+  durationMs: number;
+  engineOk?: boolean;
+  passed: number;
+  warnings: number;
+  failed: number;
+  checks: PreflightCheck[];
+}
+
+/** Map a bind/alias host to a connectable address. `0.0.0.0`/`::` are bind-only. */
+function normalizeProbeHost(host: string | undefined, fallback = '127.0.0.1'): string {
+  if (!host) return fallback;
+  const h = host.trim().replace(/^\[|\]$/g, '');
+  if (h === '0.0.0.0' || h === '::' || h === 'localhost' || h === 'localhost.localdomain') return fallback;
+  return h;
+}
+
+/** Parse a mongodb:// or redis:// URL into a host/port pair with defaults applied. */
+function endpointFromUrl(uri: string, defaultPort: number, defaultHost = '127.0.0.1'): { host: string; port: number } {
+  let host = defaultHost;
+  let port = defaultPort;
+  try {
+    const u = new URL(uri);
+    if (u.hostname) host = u.hostname;
+    if (u.port) port = Number(u.port) || defaultPort;
+  } catch {
+    /* fall back to defaults */
+  }
+  return { host: normalizeProbeHost(host), port };
+}
+
+type Category = 'refused' | 'timeout' | 'dns' | 'http' | 'other';
+
+function classifyTransient(err: unknown): { category: Category; message: string } {
+  const code = (err as { code?: string })?.code;
+  const why = (err as { cause?: unknown })?.cause;
+  const causeCode = (why as { code?: string })?.code;
+  if (code === 'ECONNREFUSED' || causeCode === 'ECONNREFUSED') {
+    return { category: 'refused', message: 'connection refused — is the service running?' };
+  }
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN' || causeCode === 'ENOTFOUND' || causeCode === 'EAI_AGAIN') {
+    return { category: 'dns', message: 'host not found' };
+  }
+  if (code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT' || causeCode === 'ETIMEDOUT' || code === 'ABORT_ERR') {
+    return { category: 'timeout', message: 'timed out — no response within the probe window' };
+  }
+  return { category: 'other', message: (err as Error).message || String(err) };
+}
+
+function httpProbe(url: string, timeoutMs: number): Promise<PreflightCheck> {
+  const start = Date.now();
+  return fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' })
+    .then((res) => {
+      const ok = res.status < 400;
+      return {
+        name: '',
+        kind: 'http',
+        url,
+        ok,
+        status: res.status,
+        latencyMs: Date.now() - start,
+        errorCategory: ok ? null : 'http',
+        error: ok ? null : `HTTP ${res.status}`,
+      };
+    })
+    .catch((err: unknown) => {
+      const { category, message } = classifyTransient(err);
+      return {
+        name: '',
+        kind: 'http',
+        url,
+        ok: false,
+        status: null,
+        latencyMs: Date.now() - start,
+        errorCategory: category,
+        error: sanitize(message),
+      };
+    });
+}
+
+function tcpProbe(host: string, port: number, timeoutMs: number): Promise<PreflightCheck> {
+  const start = Date.now();
+  return new Promise<PreflightCheck>((resolve) => {
+    const socket = createConnection({ host, port });
+    const settled = (check: PreflightCheck) => {
+      socket.destroy();
+      resolve(check);
+    };
+    let connected = false;
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => {
+      connected = true;
+      settled({
+        name: '',
+        kind: 'tcp',
+        host,
+        port,
+        ok: true,
+        latencyMs: Date.now() - start,
+        errorCategory: null,
+        error: null,
+      });
+    });
+    socket.once('error', (err: NodeJS.ErrnoException) => {
+      if (connected) return;
+      const { category, message } = classifyTransient(err);
+      settled({
+        name: '',
+        kind: 'tcp',
+        host,
+        port,
+        ok: false,
+        latencyMs: Date.now() - start,
+        errorCategory: category,
+        error: sanitize(message),
+      });
+    });
+    socket.once('timeout', () => {
+      if (connected) return;
+      settled({
+        name: '',
+        kind: 'tcp',
+        host,
+        port,
+        ok: false,
+        latencyMs: Date.now() - start,
+        errorCategory: 'timeout',
+        error: 'timed out — no response within the probe window',
+      });
+    });
+  });
+}
+
+/** Raw error strings that carry no diagnostic value. */
+const NOISE = /address(?:not valid| already in use)|WinError/i;
+
+function sanitize(message: string): string {
+  return NOISE.test(message) ? 'unreachable from this host' : message;
+}
+
+/**
+ * Derive the AI liveness URL from its OpenAI-compatible base URL.
+ *
+ * `config.ai.serverUrl` is the OpenAI base (`http://host:port/v1`) that the AI
+ * client appends `/chat/completions`, `/models`, etc. to. The FastAPI server
+ * exposes liveness at the *origin* root (`/health`), so append the health path
+ * to the origin — not to the `/v1` base.
+ */
+export function aiHealthUrl(serverUrl: string, host: string): string {
+  try {
+    const u = new URL(serverUrl);
+    const h = normalizeProbeHost(u.hostname);
+    return `${u.protocol}//${h}${u.port ? `:${u.port}` : ''}/health`;
+  } catch {
+    return `http://${host}:8000/health`;
+  }
+}
+
+export interface PreflightOptions {
+  /** True when a GraphQL gateway is actually mounted (probe it); false to skip. */
+  graphqlMounted?: boolean;
+}
+
+/** Register `POST /admin/preflight` (guarded by the caller's /admin middleware). */
+export function registerPreflightRoutes(router: Router, config: NexusConfig, opts: PreflightOptions = {}): void {
+  router.post('/admin/preflight', async (ctx) => {
+    const started = Date.now();
+    const serverUrlRaw = config.ai?.serverUrl ?? 'http://localhost:8000';
+    const serverUrl = serverUrlRaw.replace(/\/+$/, '');
+    const host = normalizeProbeHost(config.server.host);
+    const port = config.server.port ?? 8080;
+
+    const targets: PreflightTarget[] = [];
+
+    const backendUrl = `http://${host}:${port}/health`;
+    targets.push({ name: 'Backend API', kind: 'http', url: backendUrl, timeout: 3000 });
+
+    targets.push({ name: 'AI server', kind: 'http', url: aiHealthUrl(serverUrl, host), timeout: 3000 });
+
+    if (config.graphql?.path && opts.graphqlMounted) {
+      // A bare GET would 400 (no query) and POST is CSRF-blocked — probe with a
+      // minimal read-query so the endpoint answers 200 instead.
+      const graphqlUrl = `http://${host}:${port}${config.graphql.path}?query=${encodeURIComponent('{ __typename }')}`;
+      targets.push({ name: 'GraphQL', kind: 'http', url: graphqlUrl, timeout: 3000 });
+    }
+
+    // Mongo + Redis as TCP reachability probes (authenticated ping is out of scope here).
+    const dbUri = config.db?.uri ?? 'mongodb://127.0.0.1:27017';
+    const mongo = endpointFromUrl(dbUri, 27017);
+    targets.push({ name: 'MongoDB', kind: 'tcp', host: mongo.host, port: mongo.port, timeout: 2000 });
+
+    const redisUrl = config.redis?.url ?? '';
+    if (redisUrl) {
+      const redis = endpointFromUrl(redisUrl, 6379);
+      targets.push({ name: 'Redis', kind: 'tcp', host: redis.host, port: redis.port, timeout: 2000 });
+    }
+
+    const runner = async (t: PreflightTarget): Promise<PreflightCheck> => {
+      if (t.kind === 'http') {
+        return httpProbe(t.url ?? '', t.timeout ?? 3000).then((c) => ({ ...c, name: t.name }));
+      }
+      return tcpProbe(t.host ?? '127.0.0.1', t.port ?? 0, t.timeout ?? 2000).then((c) => ({ ...c, name: t.name }));
+    };
+
+    const checks = await Promise.all(targets.map(runner));
+    const durationMs = Date.now() - started;
+
+    const failed = checks.filter((c) => !c.ok);
+    const passed = checks.filter((c) => c.ok);
+    const slow = passed.filter((c) => typeof c.latencyMs === 'number' && (c.latencyMs as number) > 800);
+    const rest = passed.filter((c) => !slow.includes(c));
+
+    ctx.json({
+      ranAt: new Date().toISOString(),
+      durationMs,
+      engineOk: true,
+      passed: passed.length,
+      warnings: slow.length,
+      failed: failed.length,
+      checks: [...failed, ...slow, ...rest],
+    } satisfies PreflightReport);
+  });
+}

package/src/app/roleCatalog.ts

@@ -0,0 +1,78 @@
+/**
+ * Role catalog for the admin console.
+ *
+ * Describes every assignable role: what the holder CAN do (grants) and what
+ * they are RESTRICTED from (restricts), plus an icon, accent color and short
+ * blurb. The catalog is returned to the admin UI (`GET /admin/roles`) so role
+ * editors show accurate, useful boxes. Enforcement stays role-name based via
+ * the auth `requireRole` middleware (only `admin` can reach /admin/*).
+ */
+
+export interface RolePermission {
+  label: string;
+  detail: string;
+}
+
+export interface RoleDefinition {
+  /** Role value stored on the user document. */
+  id: string;
+  /** Human-readable role name. */
+  label: string;
+  /** Icon shown in the chip / box. */
+  icon: string;
+  /** Accent color used for the role chip / box accent. */
+  accent: string;
+  /** One-line description. */
+  description: string;
+  /** Things the role CAN do. */
+  grants: RolePermission[];
+  /** Things the role is RESTRICTED from doing. */
+  restricts: RolePermission[];
+}
+
+export const ROLE_CATALOG: RoleDefinition[] = [
+  {
+    id: 'admin',
+    label: 'Administrator',
+    icon: '◈',
+    accent: '#63bdff',
+    description: 'Full operational control of this Nexus project — services, configuration, data, payments and team access.',
+    grants: [
+      { label: 'Manage users & roles', detail: 'View every account and assign or revoke roles for other users.' },
+      { label: 'Restart services', detail: 'Stop, start and restart backend, frontend and AI services.' },
+      { label: 'Edit runtime configuration', detail: 'Change runtime.json overrides and the human-edited config file.' },
+      { label: 'Manage environment variables', detail: 'Read masked env values and update keys in the project .env.' },
+      { label: 'Administer plugins', detail: 'See and configure plugin extensions and their admin surfaces.' },
+      { label: 'Manage databases', detail: 'Create, rename and drop databases and collections; preview documents.' },
+      { label: 'Operate payments', detail: 'Review orders, transactions and provider status; create test orders.' },
+      { label: 'Monitor the build', detail: 'View live metrics, uptime, PID and process health.' },
+      { label: 'Generate AI schemas', detail: 'Produce MongoDB schemas and models from natural language.' },
+    ],
+    restricts: [
+      { label: 'Read stored password hashes', detail: 'Hashes are excluded from every user query; they are never returned to any client.' },
+      { label: 'Read secret values', detail: 'Env and payment secrets are masked — real values stay on disk and in memory only.' },
+      { label: 'Escape the project root', detail: 'Uploads, config and database paths are confined to the project directory.' },
+    ],
+  },
+  {
+    id: 'user',
+    label: 'Member',
+    icon: '◎',
+    accent: '#8ba0bd',
+    description: 'A standard end-user account. Can use the application and manage their own profile.',
+    grants: [
+      { label: 'Own account', detail: 'Register, sign in, and manage their own profile and sessions.' },
+      { label: 'Application data', detail: 'Use the app and its data, scoped to their own account.' },
+    ],
+    restricts: [
+      { label: 'Admin console', detail: 'No /admin/* endpoints are accessible — the console requires the admin role.' },
+      { label: 'Service & config control', detail: 'Runtime, processes, plugins, databases and payments are read-only or hidden.' },
+      { label: 'Other accounts & secrets', detail: 'Only their own account is returned; roles and other users are internal.' },
+    ],
+  },
+];
+
+/** Look up a role's definition by id, or `undefined` if it is not assignable. */
+export function findRole(id: string): RoleDefinition | undefined {
+  return ROLE_CATALOG.find((r) => r.id === id);
+}