@bhooai/nexus-core 2.0.5 → 2.0.7

package/src/app/aiProxyModule.ts

@@ -0,0 +1,160 @@
+import type { Router, AiProviderConfig } from '../index.js';
+import { AiClient, type ChatCompletionRequest } from '@bhooai/nexus-ai-client';
+
+/**
+ * OpenAI-compatible AI routes for the admin SPA.
+ *
+ *   POST /ai/chat/completions   (streaming SSE or JSON)
+ *   GET  /ai/models
+ *
+ * The browser never calls external AI APIs directly — Node proxies:
+ *   - a configured, enabled provider with a baseUrl → direct OpenAI-compatible
+ *     fetch to its endpoint (streaming is relayed chunk-by-chunk)
+ *   - otherwise → the Python AI server via @bhooai/nexus-ai-client
+ *
+ * Node re-emits the SSE stream so CSRF + auth still apply.
+ */
+
+export interface AiProxyOptions {
+  serverUrl: string;
+  timeoutMs: number;
+  /** Live AI providers array from config (shared reference — updated in-place
+   *  by the admin provider management endpoints). */
+  providers?: AiProviderConfig[];
+}
+
+function findProvider(providers: AiProviderConfig[], id?: string): AiProviderConfig | undefined {
+  if (!id) return undefined;
+  return providers.find((p) => p.id.toLowerCase() === id.toLowerCase() && p.enabled);
+}
+
+/** Normalise a provider baseUrl to its OpenAI-compatible root (append /v1 unless it already ends in a version segment). */
+function openAiBase(baseUrl: string): string {
+  const u = baseUrl.replace(/\/+$/, '');
+  return /\/v\d+(\/)?$/.test(u) ? u : `${u}/v1`;
+}
+
+/** Relay a streaming chat request to an OpenAI-compatible provider, re-emitting SSE. */
+async function relayProviderStream(ctx: any, p: AiProviderConfig, req: ChatCompletionRequest): Promise<void> {
+  ctx.res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+  const headers: Record<string, string> = { 'content-type': 'application/json' };
+  if (p.apiKey) headers.authorization = `Bearer ${p.apiKey}`;
+  try {
+    const upstream = await fetch(`${openAiBase(p.baseUrl ?? '')}/chat/completions`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ model: req.model, messages: req.messages, stream: true }),
+    });
+    if (!upstream.ok || !upstream.body) {
+      const text = await upstream.text();
+      throw new Error(`provider responded with HTTP ${upstream.status} ${text.slice(0, 300)}`);
+    }
+    const reader = upstream.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() ?? '';
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('data: ')) ctx.res.write(`${trimmed}\n\n`);
+      }
+    }
+    ctx.res.write('data: [DONE]\n\n');
+  } catch (err) {
+    ctx.res.write(`data: ${JSON.stringify({ error: { message: String((err as Error)?.message ?? err) } })}\n\n`);
+  } finally {
+    if (!ctx.res.writableEnded) ctx.res.end();
+  }
+}
+
+/** Register the AI proxy routes (CSRF-guarded via `router.use('/ai', csrf())` in the app). */
+export function registerAiProxyRoutes(router: Router, opts: AiProxyOptions): void {
+  const client = new AiClient({ serverUrl: opts.serverUrl, timeoutMs: opts.timeoutMs });
+  const providers = opts.providers ?? [];
+
+  router.post('/ai/chat/completions', async (ctx) => {
+    const req = (ctx.body ?? {}) as ChatCompletionRequest & { provider?: string };
+
+    // Configured OpenAI-compatible provider (direct).
+    const cfgProvider = findProvider(providers, req.provider);
+    if (cfgProvider && cfgProvider.baseUrl) {
+      if (req.stream) {
+        await relayProviderStream(ctx, cfgProvider, req);
+        return;
+      }
+      const headers: Record<string, string> = { 'content-type': 'application/json' };
+      if (cfgProvider.apiKey) headers.authorization = `Bearer ${cfgProvider.apiKey}`;
+      try {
+        const upstream = await fetch(`${openAiBase(cfgProvider.baseUrl)}/chat/completions`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify({ model: req.model, messages: req.messages }),
+        });
+        const data = await upstream.json().catch(() => ({})) as any;
+        if (!upstream.ok) {
+          ctx.json({ error: { message: (data as { error?: { message?: string } })?.error?.message ?? `provider responded with HTTP ${upstream.status}` } }, upstream.status === 401 ? 401 : 502);
+          return;
+        }
+        ctx.json(data);
+      } catch (err) {
+        ctx.json({ error: { message: String((err as Error)?.message ?? err) } }, 502);
+      }
+      return;
+    }
+
+    // Default: proxy to the Python AI server.
+    if (req.stream) {
+      ctx.res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      try {
+        for await (const chunk of client.chatStream(req)) ctx.res.write(`data: ${JSON.stringify(chunk)}\n\n`);
+        ctx.res.write('data: [DONE]\n\n');
+      } catch (err) {
+        ctx.res.write(`data: ${JSON.stringify({ error: { message: String((err as Error)?.message ?? err) } })}\n\n`);
+      } finally {
+        if (!ctx.res.writableEnded) ctx.res.end();
+      }
+      return;
+    }
+    try {
+      ctx.json(await client.chat(req));
+    } catch (err) {
+      ctx.json({ error: { message: String((err as Error)?.message ?? err) } }, (err as { status?: number })?.status ?? 502);
+    }
+  });
+
+  // Provider-aware model listing.
+  router.get('/ai/models', async (ctx) => {
+    const provider = typeof ctx.query['provider'] === 'string' ? (ctx.query['provider'] as string) : undefined;
+
+    const cfgProvider = findProvider(providers, provider);
+    if (cfgProvider && cfgProvider.baseUrl) {
+      const headers: Record<string, string> = {};
+      if (cfgProvider.apiKey) headers.authorization = `Bearer ${cfgProvider.apiKey}`;
+      try {
+        const upstream = await fetch(`${openAiBase(cfgProvider.baseUrl)}/models`, { headers });
+        const data = await upstream.json().catch(() => ({})) as any;
+        if (!upstream.ok) {
+          ctx.json({ provider: cfgProvider.id, data: [], error: (data as { error?: { message?: string } })?.error?.message ?? `provider responded with HTTP ${upstream.status}` });
+          return;
+        }
+        const models = Array.isArray(data?.data)
+          ? (data.data as any[]).map((m: any) => ({ id: String(m.id ?? m), owned_by: m.owned_by ?? cfgProvider.id }))
+          : [];
+        ctx.json({ provider: cfgProvider.id, data: models });
+      } catch (err) {
+        ctx.json({ provider: cfgProvider.id, data: [], error: String((err as Error)?.message ?? err) });
+      }
+      return;
+    }
+
+    try {
+      ctx.json(await client.listModels(provider));
+    } catch (err) {
+      ctx.json({ error: { message: String((err as Error)?.message ?? err) } }, (err as { status?: number })?.status ?? 502);
+    }
+  });
+}

package/src/app/aiSchemaModule.ts

@@ -0,0 +1,130 @@
+import type { Router, AiProviderConfig } from '../index.js';
+import { AiClient } from '@bhooai/nexus-ai-client';
+
+/**
+ * AI-enabled MongoDB schema generation for the admin app.
+ *
+ *   POST /admin/schemas/generate — generate a MongoDB $jsonSchema from text
+ *
+ * Provider data (keys, enabled state) lives in the adminModule's shared
+ * `providers` array; this module only needs the AI server + model defaults.
+ */
+
+export interface SchemaAIOptions {
+  serverUrl: string;
+  timeoutMs: number;
+  /** Model to use for generation (config: `ai.schemaModel`). */
+  model?: string;
+  /** AI providers from config (used to resolve provider model defaults). */
+  providers?: AiProviderConfig[];
+}
+
+export interface GeneratedSchema {
+  collection: string;
+  fields: Array<{ name: string; type: string; required?: boolean; unique?: boolean; enum?: string[]; description?: string }>;
+  jsonSchema: { $jsonSchema: { bsonType: string; required?: string[]; properties: Record<string, unknown> } };
+  model: string;
+}
+
+const SYSTEM_PROMPT = `You are a MongoDB schema designer. Given the user's description of the data they want to store, produce ONLY a valid JSON object — no markdown fences, no commentary — shaped exactly like this:
+
+{
+  "collection": "<plural, snake_case collection name>",
+  "fields": [
+    { "name": "<field>", "type": "String|Number|Boolean|Date|ObjectId|Array|Mixed", "required": false, "unique": false, "enum": ["a","b"], "description": "<short note>" }
+  ],
+  "jsonSchema": { "$jsonSchema": { "bsonType": "object", "required": ["..."], "properties": { "<field>": { "bsonType": "..." } } } }
+}
+
+Rules:
+- Every listed field must appear in properties with a matching bsonType (string, int/double/long, bool, date, objectId, array, object).
+- required lists only fields marked required: true. unique fields must be marked with a unique index note in their description.
+- Give the collection a sensible plural snake_case name.`;
+
+/** Register `POST /admin/schemas/generate`. */
+export function registerAiSchemaRoutes(router: Router, opts: SchemaAIOptions): void {
+  router.post('/admin/schemas/generate', async (ctx) => {
+    const body = (ctx.body ?? {}) as { prompt?: unknown; model?: unknown; provider?: unknown };
+    const prompt = typeof body.prompt === 'string' && body.prompt.trim() ? body.prompt.trim() : '';
+    if (!prompt) {
+      ctx.json({ error: 'prompt (string) is required — describe the data you want to store' }, 400);
+      return;
+    }
+    const usedModel = typeof body.model === 'string' && body.model.trim() ? body.model.trim() : (opts.model ?? 'gpt-4o-mini');
+
+    const ai = new AiClient({ serverUrl: opts.serverUrl, timeoutMs: opts.timeoutMs });
+    let text: string;
+    try {
+      const reply = await ai.chat({
+        model: usedModel,
+        temperature: 0,
+        provider: body.provider === 'auto' || body.provider === undefined ? undefined : String(body.provider),
+        messages: [
+          { role: 'system', content: SYSTEM_PROMPT },
+          { role: 'user', content: prompt },
+        ],
+      });
+      text = reply.choices?.[0]?.message?.content ?? '';
+    } catch (e) {
+      ctx.json({ error: `AI server error: ${(e as Error).message}` }, 502);
+      return;
+    }
+
+    let parsed: GeneratedSchema;
+    try {
+      parsed = extractSchema(text);
+    } catch (e) {
+      ctx.json({ error: `AI response was not a usable schema: ${(e as Error).message}` }, 502);
+      return;
+    }
+    ctx.json({ ...parsed, model: usedModel });
+  });
+}
+
+/** Parse the AI reply (tolerates markdown fences and stray prose around the JSON). */
+function extractSchema(text: string): GeneratedSchema {
+  const cleaned = stripFences(text).trim();
+  const start = cleaned.indexOf('{');
+  const end = cleaned.lastIndexOf('}');
+  if (start === -1 || end <= start) throw new Error('no JSON object found in the response');
+  const parsed = JSON.parse(cleaned.slice(start, end + 1)) as {
+    collection?: unknown;
+    fields?: unknown;
+    jsonSchema?: unknown;
+  };
+
+  if (typeof parsed.collection !== 'string' || !/^[A-Za-z][A-Za-z0-9_]*$/.test(parsed.collection)) {
+    throw new Error(`invalid collection name from AI: ${String(parsed.collection)}`);
+  }
+  if (!Array.isArray(parsed.fields)) throw new Error('"fields" must be an array');
+  const schema = parsed.jsonSchema as { $jsonSchema?: unknown } | undefined;
+  const jsonSchema = schema?.$jsonSchema as Record<string, unknown> | undefined;
+  if (!jsonSchema || jsonSchema.bsonType !== 'object' || typeof jsonSchema.properties !== 'object' || jsonSchema.properties === null) {
+    throw new Error('"jsonSchema" must contain $jsonSchema with bsonType "object" and properties');
+  }
+
+  const fields = parsed.fields.map((f) => {
+    const raw = (f ?? {}) as Record<string, unknown>;
+    return {
+      name: String(raw.name ?? ''),
+      type: String(raw.type ?? 'Mixed'),
+      required: !!raw.required,
+      unique: !!raw.unique,
+      enum: Array.isArray(raw.enum) ? (raw.enum as string[]).map(String) : undefined,
+      description: typeof raw.description === 'string' ? raw.description : undefined,
+    };
+  });
+  if (!fields.length || fields.some((f) => !f.name)) throw new Error('fields must have unique names');
+
+  return {
+    collection: parsed.collection,
+    fields,
+    jsonSchema: { $jsonSchema: jsonSchema as GeneratedSchema['jsonSchema']['$jsonSchema'] },
+    model: '',
+  };
+}
+
+function stripFences(text: string): string {
+  const m = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+  return m ? m[1]! : text;
+}

package/src/app/authModule.ts

@@ -0,0 +1,243 @@
+/**
+ * authModule — framework-provided /auth/* routes (register/login/refresh/logout/me).
+ *
+ * Auto-mounted by `createNexusApp()` when `config.admin.enabled`. Uses the
+ * `@bhooai/nexus-auth` primitives (AuthService, MemorySessionStore, CSRF, OAuth)
+ * and the framework User model (see `userModel.ts`). The very first registered
+ * user is bootstrapped as an admin.
+ *
+ * Routes:
+ *   POST /auth/register          — create a user (first user → admin) + sign in
+ *   POST /auth/login             — verify credentials + sign in
+ *   POST /auth/refresh           — rotate the refresh token (HttpOnly cookie)
+ *   POST /auth/logout            — end the session + clear cookies
+ *   GET  /auth/me                — current user (auth-guarded)
+ *   PUT  /auth/profile           — update display name (auth-guarded)
+ *   POST /auth/change-password   — verify current, set new (auth-guarded)
+ *   GET  /auth/google            — OAuth start (only if configured)
+ *   GET  /auth/google/callback   — OAuth callback (only if configured)
+ *   GET  /auth/facebook          — OAuth start (only if configured)
+ *   GET  /auth/facebook/callback — OAuth callback (only if configured)
+ */
+import type { NexusConfig } from '../config/types.js';
+import type { Router } from '../http/Router.js';
+import {
+  AuthService,
+  MemorySessionStore,
+  authToken,
+  requireAuth,
+  setAuthCookies,
+  clearAuthCookies,
+  readCookieValue,
+  hashPassword,
+  verifyPassword,
+  buildGoogleAuthUrl,
+  buildFacebookAuthUrl,
+  exchangeGoogleCode,
+  exchangeFacebookCode,
+  fetchGoogleProfile,
+  fetchFacebookProfile,
+  generateState,
+  generatePkceVerifier,
+  MemoryOAuthStateStore,
+  type GoogleOAuthConfig,
+  type FacebookOAuthConfig,
+} from '@bhooai/nexus-auth';
+import { ConflictError, AuthenticationError, ValidationError } from '../index.js';
+import { ObjectId } from '@bhooai/nexus-data';
+import { initUserModel, getUserModel, findUserForLogin, upsertOAuthUser, type UserInstance } from './userModel.js';
+
+const sessions = new MemorySessionStore();
+const oauthState = new MemoryOAuthStateStore();
+
+function origin(config: NexusConfig): string {
+  const proto = config.server.https ? 'https' : 'http';
+  return `${proto}://${config.server.host === '0.0.0.0' ? 'localhost' : config.server.host}:${config.server.port}`;
+}
+
+function jwtOptions(config: NexusConfig) {
+  return {
+    secret: config.auth.jwt.secret ?? 'nexus-insecure-secret-change-me',
+    algorithm: 'HS256' as const,
+    issuer: config.auth.jwt.issuer,
+    audience: config.auth.jwt.audience,
+    accessTtl: config.auth.jwt.accessTtl,
+    refreshTtl: config.auth.jwt.refreshTtl,
+  };
+}
+
+function authService(config: NexusConfig): AuthService {
+  return new AuthService(jwtOptions(config), sessions);
+}
+
+/** Register /auth/* routes onto the given router. Call after `connect()` + `initUserModel()`. */
+export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCreated?: () => void): AuthService {
+  initUserModel();
+  const service = authService(config);
+
+  // POST /auth/register
+  router.post('/auth/register', async (ctx) => {
+    const body = (ctx.body ?? {}) as { email?: string; password?: string; name?: string };
+    if (!body.email || !body.password) throw new ValidationError('email and password are required');
+    if (body.password.length < 8) throw new ValidationError('password must be at least 8 characters');
+
+    const User = getUserModel();
+    const existing = await User.findOne({ email: body.email.toLowerCase() }).lean();
+    if (existing) throw new ConflictError('A user with that email already exists');
+
+    const passwordHash = await hashPassword(body.password);
+    // Bootstrap: the very first registered user becomes an admin.
+    const userCount = await User.countDocuments();
+    const roles = userCount === 0 ? ['admin'] : ['user'];
+    const [user] = await User.create({ email: body.email, name: body.name, passwordHash, roles });
+    // Notify subscribers (e.g. a GraphQL `userCount` subscription) if wired.
+    onUserCreated?.();
+    const pair = await service.login({ userId: String((user as UserInstance)._id), roles: (user as UserInstance).roles, meta: { ip: ctx.req.socket.remoteAddress } });
+    setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+    ctx.json({ user: publicUser(user), accessToken: pair.accessToken, refreshToken: pair.refreshToken });
+  });
+
+  // POST /auth/login
+  router.post('/auth/login', async (ctx) => {
+    const body = (ctx.body ?? {}) as { email?: string; password?: string };
+    if (!body.email || !body.password) throw new ValidationError('email and password are required');
+    const user = await findUserForLogin(body.email);
+    if (!user || !user.passwordHash) throw new AuthenticationError('Invalid email or password');
+    const ok = await verifyPassword(body.password, user.passwordHash);
+    if (!ok) throw new AuthenticationError('Invalid email or password');
+    const pair = await service.login({ userId: String(user._id), roles: user.roles });
+    setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+    ctx.json({ user: publicUser(user), accessToken: pair.accessToken, refreshToken: pair.refreshToken });
+  });
+
+  // POST /auth/refresh
+  router.post('/auth/refresh', async (ctx) => {
+    const body = (ctx.body ?? {}) as { refreshToken?: string };
+    const refreshToken = body.refreshToken ?? readCookieValue(ctx, config.auth.refreshCookieName);
+    if (!refreshToken) throw new AuthenticationError('Missing refresh token');
+    const pair = await service.refresh(refreshToken);
+    setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+    ctx.json({ accessToken: pair.accessToken, refreshToken: pair.refreshToken });
+  });
+
+  // POST /auth/logout
+  router.post('/auth/logout', async (ctx) => {
+    // Optional auth: end the session if a token is present, but never 401 on logout.
+    await authToken(service, { required: false, allowCookie: true, cookieName: config.auth.cookieName })(ctx, async () => {});
+    const sid = (ctx.state.user as { sid?: string } | undefined)?.sid;
+    if (sid) await service.logout(sid);
+    clearAuthCookies(ctx, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+    ctx.json({ ok: true });
+  });
+
+  // GET /auth/me
+  router.get('/auth/me', async (ctx) => {
+    const User = getUserModel();
+    const id = (ctx.state.user as { id: string }).id;
+    const user = await User.findById(id).lean();
+    ctx.json({ user: publicUser(user) });
+  }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
+
+  // PUT /auth/profile — update the signed-in user's display name.
+  router.put('/auth/profile', async (ctx) => {
+    const body = (ctx.body ?? {}) as { name?: string };
+    const name = typeof body.name === 'string' ? body.name.trim() : '';
+    if (!name) throw new ValidationError('name is required');
+    const id = (ctx.state.user as { id: string }).id;
+    const User = getUserModel();
+    await User.updateOne({ _id: id }, { $set: { name } });
+    const user = await User.findById(id).lean();
+    ctx.json({ ok: true, user: publicUser(user) });
+  }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
+
+  // POST /auth/change-password — verify the current password, then set a new one.
+  router.post('/auth/change-password', async (ctx) => {
+    const body = (ctx.body ?? {}) as { currentPassword?: string; newPassword?: string };
+    if (!body.currentPassword) throw new ValidationError('current password is required');
+    if (!body.newPassword || body.newPassword.length < 8) throw new ValidationError('password must be at least 8 characters');
+
+    const id = (ctx.state.user as { id: string }).id;
+    const User = getUserModel();
+    const coll = await User.collection;
+    const raw = await coll.findOne({ _id: new ObjectId(id) });
+    if (!raw) throw new AuthenticationError('User not found');
+    const passwordHash = raw.passwordHash as string | undefined;
+    if (!passwordHash) throw new AuthenticationError('This account has no password (OAuth account)');
+    const ok = await verifyPassword(body.currentPassword, passwordHash);
+    if (!ok) throw new AuthenticationError('Current password is incorrect');
+    const nextHash = await hashPassword(body.newPassword);
+    await User.updateOne({ _id: id }, { $set: { passwordHash: nextHash } });
+    ctx.json({ ok: true });
+  }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
+
+  // ── OAuth: Google ──────────────────────────────────────────────────────────
+  if (config.auth.google?.clientId) {
+    const google: GoogleOAuthConfig = {
+      clientId: config.auth.google.clientId,
+      clientSecret: config.auth.google.clientSecret,
+      redirectUri: `${origin(config)}${config.auth.google.callbackPath}`,
+      scope: config.auth.google.scope.split(/\s+/).filter(Boolean),
+    };
+    router.get('/auth/google', async (ctx) => {
+      const state = generateState();
+      const verifier = generatePkceVerifier();
+      await oauthState.set(state, { provider: 'google', verifier }, 5 * 60_000);
+      ctx.redirect(buildGoogleAuthUrl(google, { state, verifier }));
+    });
+    router.get(config.auth.google.callbackPath, async (ctx) => {
+      const code = ctx.query.code as string | undefined;
+      const state = ctx.query.state as string | undefined;
+      if (!code || !state) throw new AuthenticationError('Missing OAuth code/state');
+      const data = await oauthState.consume(state);
+      if (!data || data.provider !== 'google') throw new AuthenticationError('Invalid OAuth state');
+      const tokens = await exchangeGoogleCode(code, google, data.verifier as string);
+      const profile = await fetchGoogleProfile(tokens.accessToken);
+      const user = await upsertOAuthUser({ provider: 'google', providerUserId: profile.providerUserId, email: profile.email, name: profile.name });
+      const pair = await service.login({ userId: String(user._id), roles: user.roles });
+      setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+      ctx.json({ user: publicUser(user), accessToken: pair.accessToken });
+    });
+  }
+
+  // ── OAuth: Facebook ─────────────────────────────────────────────────────────
+  if (config.auth.facebook?.clientId) {
+    const facebook: FacebookOAuthConfig = {
+      clientId: config.auth.facebook.clientId,
+      clientSecret: config.auth.facebook.clientSecret,
+      redirectUri: `${origin(config)}${config.auth.facebook.callbackPath}`,
+      scope: config.auth.facebook.scope.split(/\s+/).filter(Boolean),
+    };
+    router.get('/auth/facebook', async (ctx) => {
+      const state = generateState();
+      await oauthState.set(state, { provider: 'facebook' }, 5 * 60_000);
+      ctx.redirect(buildFacebookAuthUrl(facebook, state));
+    });
+    router.get(config.auth.facebook.callbackPath, async (ctx) => {
+      const code = ctx.query.code as string | undefined;
+      const state = ctx.query.state as string | undefined;
+      if (!code || !state) throw new AuthenticationError('Missing OAuth code/state');
+      const data = await oauthState.consume(state);
+      if (!data || data.provider !== 'facebook') throw new AuthenticationError('Invalid OAuth state');
+      const tokens = await exchangeFacebookCode(code, facebook);
+      const profile = await fetchFacebookProfile(tokens.accessToken);
+      const user = await upsertOAuthUser({ provider: 'facebook', providerUserId: profile.providerUserId, email: profile.email, name: profile.name });
+      const pair = await service.login({ userId: String(user._id), roles: user.roles });
+      setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+      ctx.json({ user: publicUser(user), accessToken: pair.accessToken });
+    });
+  }
+
+  return service;
+}
+
+function publicUser(user: unknown): Record<string, unknown> | null {
+  if (!user) return null;
+  // DocumentInstance → use toObject() (avoids spreading the Proxy and its circular _model).
+  // Plain objects (raw lean docs / JWT claims) → spread directly.
+  const obj =
+    (user as { toObject?: () => Record<string, unknown> }).toObject?.() ??
+    (user as Record<string, unknown>);
+  const u = { ...obj };
+  delete u.passwordHash;
+  return u;
+}

package/src/app/createNexusApp.ts

@@ -32,6 +32,11 @@ import { policyRegistry } from './policies.js';
 import { configureStorageFromEnv } from './Storage.js';
 import { maintenanceMiddleware } from './maintenance.js';
 import { createLazyDb, registerAdminRoutes, RequestLogBuffer } from './adminModule.js';
+import { registerAuthRoutes } from './authModule.js';
+import { issueCsrfToken, csrf, authToken, requireRole } from '@bhooai/nexus-auth';
+import { connect } from '@bhooai/nexus-data';
+import { createGateway, graphqlHttpHandler } from '@bhooai/nexus-graphql';
+import type { Subgraph } from '@bhooai/nexus-graphql';
 
 export interface CreateNexusAppOptions {
   /** Identifier for this backend, used in admin, telemetry, logs. */
@@ -230,6 +235,40 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     ctx.json({ apps });
   });
 
+  // ------------------------------------------------------------------
+  // GraphQL gateway — compose discovered subgraphs into a /graphql endpoint
+  // ------------------------------------------------------------------
+  let graphqlMounted = false;
+  if (discovery.graphql.length > 0) {
+    try {
+      const subgraphs: Subgraph[] = [];
+      for (const file of discovery.graphql) {
+        const sg = await importDefault<Subgraph>(file);
+        if (sg && typeof sg === 'object' && 'sdl' in sg && 'resolvers' in sg) {
+          subgraphs.push(sg);
+        } else {
+          console.warn(`[${name}] graphql file ${file.path} does not export a subgraph — skipped`);
+        }
+      }
+      if (subgraphs.length === 1) {
+        const gateway = createGateway({ subgraph: subgraphs[0]! });
+        const graphqlPath = config.graphql?.path ?? '/graphql';
+        const handler = graphqlHttpHandler({
+          gateway,
+          introspection: config.graphql?.introspection ?? true,
+        });
+        router.add('GET', graphqlPath, handler);
+        router.add('POST', graphqlPath, handler);
+        graphqlMounted = true;
+        console.log(`[${name}] GraphQL gateway mounted at ${graphqlPath}`);
+      } else if (subgraphs.length > 1) {
+        console.warn(`[${name}] found ${subgraphs.length} subgraphs — multi-subgraph federation is Phase 6; GraphQL not mounted`);
+      }
+    } catch (err) {
+      console.warn(`[${name}] failed to mount GraphQL gateway:`, err);
+    }
+  }
+
   // ------------------------------------------------------------------
   // Admin module — request log buffer, lazy DB, admin + AI proxy routes
   // ------------------------------------------------------------------
@@ -237,7 +276,35 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   const lazyDb = createLazyDb(config);
 
   if (config.admin.enabled) {
-    registerAdminRoutes(router, { name, config, projectRoot }, logBuffer, lazyDb);
+    // Connect to MongoDB + register the User model so /auth/* can work.
+    try {
+      connect(config.db.uri, { autoIndex: config.db.autoIndex });
+    } catch { /* Mongo unreachable — auth routes will fail lazily */ }
+
+    // Auth routes (register/login/refresh/logout/me + OAuth). Returns the
+    // AuthService used to build the admin guard.
+    const authService = registerAuthRoutes(router, config);
+
+    // CSRF token endpoint — mints a double-submit token cookie + returns it.
+    router.get('/csrf-token', (ctx) => {
+      const token = issueCsrfToken(ctx);
+      ctx.json({ token });
+    });
+
+    // Guard all /admin/* routes with bearer-token auth + the 'admin' role.
+    const guard: Middleware[] = [
+      authToken(authService, { cookieName: config.auth.cookieName }),
+      requireRole('admin'),
+    ];
+
+    // CSRF protection (double-submit cookie) on the auth + admin surfaces.
+    router.use('/auth', csrf());
+    router.use('/admin', csrf());
+    // The admin SPA's AI proxy calls (POST /ai/chat/completions) carry the
+    // same double-submit token — safe methods (GET /ai/models) stay exempt.
+    router.use('/ai', csrf());
+
+    registerAdminRoutes(router, { name, config, projectRoot, graphqlMounted }, logBuffer, lazyDb, guard);
   }
 
   // ------------------------------------------------------------------
@@ -260,7 +327,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // Maintenance mode (checked first)
   server.use(maintenanceMiddleware({ projectRoot }));
 
-  // Request logging into the ring buffer (source for /admin/logs/tail).
+  // Request logging into the ring buffer (source for /admin/logs/tail + /admin/requests).
   server.use(async (ctx, next) => {
     const start = performance.now();
     const res = ctx.res;
@@ -268,12 +335,16 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (res as any).end = (...args: any[]) => {
       const latencyMs = Math.round(performance.now() - start);
+      const forwardedFor = (ctx.headers['x-forwarded-for'] as string) ?? '';
       logBuffer.push({
         ts: Date.now(),
         method: ctx.method,
         path: ctx.path,
         status: res.statusCode,
         latencyMs,
+        ip: (forwardedFor.split(',')[0] ?? '').trim() || ctx.req.socket?.remoteAddress,
+        referer: (ctx.headers['referer'] as string) || undefined,
+        userAgent: (ctx.headers['user-agent'] as string) || undefined,
       });
       return originalEnd(...args);
     };