@bhooai/nexus-core 2.0.11 → 2.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-core",
-    "version": "2.0.11",
+    "version": "2.0.13",
     "publishConfig": {
         "access": "public"
     },

package/src/app/createNexusApp.ts

@@ -13,7 +13,7 @@
  *   await app.listen();
  */
 import { existsSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { resolve, dirname, join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { loadConfigAuto, type NexusConfig } from '../config/index.js';
 import { Container } from '../di/Container.js';
@@ -29,14 +29,15 @@ import { eventBus, type EventBus, type Listener } from './events.js';
 import { configureQueue, InMemoryQueueAdapter, type JobQueueAdapter } from './Job.js';
 import { configureMailDriver, configureMailRenderer, logMailDriver } from './Mailable.js';
 import { policyRegistry } from './policies.js';
-import { configureStorageFromEnv } from './Storage.js';
+import { configureStorageFromEnv, storage } from './Storage.js';
 import { maintenanceMiddleware } from './maintenance.js';
+import { serveStatic } from '../http/static.js';
 import { createLazyDb, registerAdminRoutes, RequestLogBuffer } from './adminModule.js';
 import { registerAuthRoutes } from './authModule.js';
-import { issueCsrfToken, csrf, authToken, requireRole } from '@bhooai/nexus-auth';
+import { issueCsrfToken, getCsrfToken, 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';
+import { createGateway, createFederatedGateway, graphqlHttpHandler, getExplorerHtml, helloSubgraph, SubscriptionServer } from '@bhooai/nexus-graphql';
+import type { Subgraph, GraphQLContext } from '@bhooai/nexus-graphql';
 
 export interface CreateNexusAppOptions {
   /** Identifier for this backend, used in admin, telemetry, logs. */
@@ -58,6 +59,11 @@ export interface CreateNexusAppOptions {
   /** Hooks for extending boot. */
   beforeStart?: (app: NexusApp) => Promise<void> | void;
   afterStart?: (app: NexusApp) => Promise<void> | void;
+  /**
+   * Extra values injected into every GraphQL resolver context (e.g. a payments
+   * service). Merged with the default `{ request, user }` context.
+   */
+  graphqlContext?: Record<string, unknown>;
 }
 
 export interface NexusApp {
@@ -245,37 +251,122 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   });
 
   // ------------------------------------------------------------------
-  // GraphQL gateway — compose discovered subgraphs into a /graphql endpoint
+  // GraphQL gateway — builtin hello + discovered subgraphs (federated)
   // ------------------------------------------------------------------
   let graphqlMounted = false;
-  if (discovery.graphql.length > 0) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let graphqlGateway: any = null;
+  {
+    const explorerEnabled = (config.graphql as unknown as { explorer?: boolean })?.explorer ?? true;
+    const helloEnabled = (config.graphql as unknown as { hello?: boolean })?.hello !== false;
     try {
-      const subgraphs: Subgraph[] = [];
+      const discovered: 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`);
+        try {
+          const sg = await importDefault<Subgraph>(file);
+          if (sg && typeof sg === 'object' && 'sdl' in sg && 'resolvers' in sg) {
+            // Avoid duplicate hello if user created a hello subgraph
+            if (helloEnabled && (sg as unknown as { name?: string }).name === 'hello') {
+              console.warn(`[${name}] graphql file ${file.path} defines a 'hello' subgraph — overriding builtin hello`);
+            }
+            discovered.push(sg);
+          } else {
+            console.warn(`[${name}] graphql file ${file.path} does not export a subgraph — skipped`);
+          }
+        } catch (e) {
+          console.warn(`[${name}] failed to import graphql ${file.path}:`, e);
         }
       }
-      if (subgraphs.length === 1) {
-        const gateway = createGateway({ subgraph: subgraphs[0]! });
+
+      // Builtin hello is always first unless disabled or user already provides hello
+      const hasUserHello = discovered.some((s) => s.name === 'hello');
+      const subgraphs: Subgraph[] = [];
+      if (helloEnabled && !hasUserHello) subgraphs.push(helloSubgraph);
+      subgraphs.push(...discovered);
+
+      if (subgraphs.length > 0) {
         const graphqlPath = config.graphql?.path ?? '/graphql';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let gateway: any;
+        let publicSdl: string;
+        if (subgraphs.length === 1) {
+          gateway = createGateway({ subgraph: subgraphs[0]! });
+          publicSdl = (subgraphs[0] as unknown as { sdl?: string })?.sdl ?? '';
+        } else {
+          gateway = createFederatedGateway(subgraphs);
+          // mergedSdl is client-facing SDL (no federation directives)
+          publicSdl = (gateway as unknown as { supergraph?: { mergedSdl?: string } })?.supergraph?.mergedSdl ?? subgraphs.map((s) => s.sdl).join('\n\n');
+          console.log(`[${name}] GraphQL federated gateway: ${subgraphs.map((s) => s.name).join(', ')} (hello builtin ${helloEnabled ? 'included' : 'disabled'})`);
+        }
         const handler = graphqlHttpHandler({
           gateway,
           introspection: config.graphql?.introspection ?? true,
+          requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true,
+          context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), ...opts.graphqlContext }),
         });
-        router.add('GET', graphqlPath, handler);
+        if (explorerEnabled) {
+          const explorerHtml = getExplorerHtml({
+            endpoint: graphqlPath,
+            appName: name,
+            sdl: publicSdl,
+            introspection: config.graphql?.introspection ?? true,
+          });
+          const explorerHandler: Handler = async (ctx) => {
+            ctx.setHeader('access-control-allow-origin', '*');
+            ctx.html(explorerHtml);
+          };
+          router.add('GET', '/graphiql', explorerHandler);
+          router.add('GET', graphqlPath, handler);
+        } else {
+          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`);
+        graphqlGateway = gateway;
+        if (subgraphs.length === 1) {
+          console.log(`[${name}] GraphQL gateway mounted at ${graphqlPath} (${subgraphs[0]!.name} subgraph${explorerEnabled ? ' + explorer at /graphiql' : ''})`);
+        } else {
+          console.log(`[${name}] GraphQL gateway mounted at ${graphqlPath}${explorerEnabled ? ' (+ explorer at /graphiql)' : ''}`);
+        }
       }
     } catch (err) {
       console.warn(`[${name}] failed to mount GraphQL gateway:`, err);
     }
+    // Fallback — should not happen because builtin hello guarantees a subgraph, but keep for hello:false
+    if (!graphqlMounted && explorerEnabled) {
+      const graphqlPath = config.graphql?.path ?? '/graphql';
+      const placeholderHtml = getExplorerHtml({
+        endpoint: graphqlPath,
+        appName: name,
+        sdl: helloEnabled ? helloSubgraph.sdl : '',
+        introspection: config.graphql?.introspection ?? true,
+      });
+      const placeholderHandler: Handler = async (ctx) => {
+        ctx.setHeader('access-control-allow-origin', '*');
+        ctx.html(placeholderHtml);
+      };
+      const graphqlPlaceholder: Handler = async (ctx) => {
+        if (helloEnabled) {
+          // hello is available even in fallback — route through its gateway
+          const gw = createGateway({ subgraph: helloSubgraph });
+          const h = graphqlHttpHandler({ gateway: gw, introspection: config.graphql?.introspection ?? true, requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true, context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), ...opts.graphqlContext }) });
+          return h(ctx);
+        }
+        ctx.json({ errors: [{ message: 'No GraphQL subgraph found. Add one with: npx nexus make:subgraph <name>  (then restart)' }] }, 404);
+      };
+      try { router.add('GET', '/graphiql', placeholderHandler); } catch {}
+      try { router.add('GET', graphqlPath, graphqlPlaceholder); } catch {}
+      try {
+        if (helloEnabled) {
+          const gw = createGateway({ subgraph: helloSubgraph });
+          router.add('POST', graphqlPath, graphqlHttpHandler({ gateway: gw, introspection: config.graphql?.introspection ?? true, requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true, context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), ...opts.graphqlContext }) }));
+        } else {
+          router.add('POST', graphqlPath, async (ctx) => ctx.json({ errors: [{ message: 'No GraphQL subgraph found. Add one with: npx nexus make:subgraph <name>' }] }, 404));
+        }
+      } catch {}
+      console.log(`[${name}] GraphQL explorer mounted at /graphiql${helloEnabled ? ' (hello builtin)' : ' (no schema — add a subgraph)'}`);
+      if (helloEnabled) graphqlMounted = true;
+    }
   }
 
   // ------------------------------------------------------------------
@@ -294,9 +385,12 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     // AuthService used to build the admin guard.
     const authService = registerAuthRoutes(router, config);
 
-    // CSRF token endpoint — mints a double-submit token cookie + returns it.
+    // CSRF token endpoint — returns the double-submit token. Reuses the existing
+    // cookie token when present (no rotation) so previously-issued tokens (e.g. a
+    // copied urlbar URL) keep matching; only mints a fresh one when none exists.
     router.get('/csrf-token', (ctx) => {
-      const token = issueCsrfToken(ctx);
+      const existing = getCsrfToken(ctx);
+      const token = existing ?? issueCsrfToken(ctx);
       ctx.json({ token });
     });
 
@@ -306,6 +400,13 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
       requireRole('admin'),
     ];
 
+    // When enabled, gate the GraphiQL explorer with the same admin guard used for
+    // /admin/* and plugin admin pages. Only /graphiql is protected; the /graphql
+    // JSON endpoint stays public.
+    if (config.graphql?.explorerRequireAuth) {
+      for (const mw of guard) router.use('/graphiql', mw);
+    }
+
     // CSRF protection (double-submit cookie) on the auth + admin surfaces.
     router.use('/auth', csrf());
     router.use('/admin', csrf());
@@ -434,6 +535,108 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     if ((e as any)?.code !== 'ERR_MODULE_NOT_FOUND') console.warn('[realtime] ws init failed:', e);
   }
 
+  // ------------------------------------------------------------------
+  // GraphQL subscriptions over WebSocket — mount when a gateway exists
+  // and config.graphql.subscriptions is enabled.
+  // ------------------------------------------------------------------
+  const graphqlSubscriptions = (config.graphql as unknown as { subscriptions?: boolean })?.subscriptions ?? true;
+  if (graphqlGateway && graphqlSubscriptions && typeof graphqlGateway.subscribe === 'function') {
+    try {
+      const subPath = `${config.graphql?.path ?? '/graphql'}/ws`;
+      new SubscriptionServer({ httpServer: server.httpServer, gateway: graphqlGateway, path: subPath });
+      console.log(`[${name}] GraphQL subscriptions mounted at ${subPath}`);
+    } catch (err) {
+      console.warn(`[${name}] failed to mount GraphQL subscriptions:`, err);
+    }
+  }
+
+  // Public uploads: serve GET /uploads/* from storage/uploads (file-storage example).
+  // This was missing — 404 `No route for GET /uploads/media/...`.
+  server.use(serveStatic(join(projectRoot, 'storage', 'uploads'), { prefix: '/uploads' }));
+
+  // Signed private files: GET /files/<encodedPath>?expires=&sig=
+  // Handles LocalDisk.signedUrl() URLs (HMAC, 5min TTL). Streams from whichever local disk holds the file.
+  server.use(async (ctx, next) => {
+    if ((ctx.method !== 'GET' && ctx.method !== 'HEAD') || (!ctx.path.startsWith('/files/') && ctx.path !== '/files')) {
+      await next();
+      return;
+    }
+    const encoded = ctx.path.slice('/files/'.length);
+    if (!encoded) {
+      ctx.json({ error: { code: 'NOT_FOUND', message: 'missing file path' } }, 404);
+      return;
+    }
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(encoded);
+    } catch {
+      ctx.json({ error: { code: 'BAD_REQUEST', message: 'invalid file path' } }, 400);
+      return;
+    }
+    // Block traversal
+    if (decoded.includes('..') || decoded.includes('\\') || decoded.startsWith('/')) {
+      ctx.json({ error: { code: 'BAD_REQUEST', message: 'invalid file path' } }, 400);
+      return;
+    }
+    const expiresRaw = ctx.query.expires;
+    const sigRaw = ctx.query.sig;
+    const expiresStr = Array.isArray(expiresRaw) ? expiresRaw[0] : (expiresRaw as string | undefined);
+    const sig = Array.isArray(sigRaw) ? sigRaw[0] : (sigRaw as string | undefined);
+    if (!expiresStr || !sig) {
+      ctx.json({ error: { code: 'UNAUTHORIZED', message: 'missing signature' } }, 401);
+      return;
+    }
+    const expires = parseInt(String(expiresStr), 10);
+    if (!Number.isFinite(expires)) {
+      ctx.json({ error: { code: 'BAD_REQUEST', message: 'invalid expires' } }, 400);
+      return;
+    }
+    const localUploads = storage.local('uploads');
+    const localPrivate = storage.local('private');
+    const verifier = localUploads ?? localPrivate;
+    const isValid = verifier ? verifier.verifySignedUrl(decoded, expires, String(sig)) : false;
+    // Fallback: also accept signature valid for private disk if uploads verifier fails (same secret, so same result — but check both)
+    const isValidAlt = !isValid && localPrivate && localUploads ? localPrivate.verifySignedUrl(decoded, expires, String(sig)) : false;
+    if (!isValid && !isValidAlt) {
+      ctx.json({ error: { code: 'FORBIDDEN', message: 'invalid or expired signature' } }, 403);
+      return;
+    }
+    // Find disk holding the file (private first, then uploads)
+    const candidates = [localPrivate, localUploads].filter(Boolean) as Array<NonNullable<typeof localPrivate>>;
+    let disk: (typeof candidates)[number] | null = null;
+    for (const d of candidates) {
+      try {
+        if (await d.exists(decoded)) { disk = d; break; }
+      } catch {}
+    }
+    if (!disk) {
+      ctx.json({ error: { code: 'NOT_FOUND', message: 'file not found' } }, 404);
+      return;
+    }
+    try {
+      if (ctx.method === 'HEAD') {
+        ctx.status(200);
+        return;
+      }
+      const stream = disk.stream(decoded);
+      const ext = decoded.includes('.') ? `.${decoded.split('.').pop()!.toLowerCase()}` : '';
+      const MIME: Record<string, string> = {
+        '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif',
+        '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf',
+        '.txt': 'text/plain; charset=utf-8', '.json': 'application/json; charset=utf-8',
+      };
+      ctx.setHeader('content-type', MIME[ext] ?? 'application/octet-stream');
+      await new Promise<void>((resolveStream, rejectStream) => {
+        stream.on('error', rejectStream);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (stream as any).pipe(ctx.res);
+        stream.on('end', resolveStream);
+      });
+    } catch {
+      ctx.json({ error: { code: 'NOT_FOUND', message: 'file not found' } }, 404);
+    }
+  });
+
   // Body parsing (JSON / urlencoded / multipart) — before everything else so
   // POST/PUT/PATCH handlers see ctx.body.
   server.use(bodyParser(config.server.bodyLimit));

package/src/app/discover.ts

@@ -76,16 +76,16 @@ export async function discoverBackend(srcRoot: string): Promise<DiscoveryResult>
 
   const [routes, graphql, rooms, mailables, errorPages, events, listeners, jobs, policies, providers, seeds, migrations, plugins, config] =
     await Promise.all([
-      collect(join(abs, 'routes'), /\.(ts|js)$/),
-      collect(join(abs, 'graphql'), /\.graph\.(ts|js)$/),
-      collect(join(abs, 'ws'), /\.room\.(ts|js)$/),
+      collectWithModules(abs, 'routes', /\.(ts|js)$/),
+      collectWithModules(abs, 'graphql', /\.graph\.(ts|js)$/),
+      collectWithModules(abs, 'ws', /\.room\.(ts|js)$/),
       collect(join(abs, 'mail', 'mailables'), /\.(ts|js)$/),
       collect(join(abs, 'errors', 'pages'), /\.html$/),
-      collect(join(abs, 'events'), /\.(ts|js)$/),
-      collect(join(abs, 'listeners'), /^On.*\.(ts|js)$/),
-      collect(join(abs, 'jobs'), /Job\.(ts|js)$/),
-      collect(join(abs, 'policies'), /Policy\.(ts|js)$/),
-      collect(join(abs, 'providers'), /ServiceProvider\.(ts|js)$/),
+      collectWithModules(abs, 'events', /\.(ts|js)$/),
+      collectWithModules(abs, 'listeners', /^On.*\.(ts|js)$/),
+      collectWithModules(abs, 'jobs', /Job\.(ts|js)$/),
+      collectWithModules(abs, 'policies', /Policy\.(ts|js)$/),
+      collectWithModules(abs, 'providers', /ServiceProvider\.(ts|js)$/),
       collect(join(abs, 'database', 'seeds'), /Seeder\.(ts|js)$/),
       collect(join(abs, 'database', 'migrations'), /^\d{4}_\d{2}_\d{2}_\d{6}_.*\.(ts|js)$/),
       collectPluginDirs(join(abs, 'plugins')),
@@ -112,6 +112,37 @@ async function collect(dir: string, pattern: RegExp): Promise<DiscoveredFile[]>
   return out;
 }
 
+/** Collect from flat root + modules/<domain>/<sub> — keeps modular workflow discoverable. */
+async function collectWithModules(abs: string, sub: string, pattern: RegExp): Promise<DiscoveredFile[]> {
+  const flat = await collect(join(abs, sub), pattern);
+  const modulesRoot = join(abs, 'modules');
+  if (!existsSync(modulesRoot)) return dedupeByPath(flat);
+  const mods = await readdir(modulesRoot, { withFileTypes: true });
+  const moduleFiles: DiscoveredFile[] = [];
+  for (const m of mods) {
+    if (!m.isDirectory()) continue;
+    const modSub = join(modulesRoot, m.name, sub);
+    const files = await collect(modSub, pattern);
+    for (const f of files) {
+      moduleFiles.push({ ...f, subdir: f.subdir ? `${m.name}/${f.subdir}` : m.name });
+    }
+  }
+  // Prefer modular file when same `name` exists in both flat and modular (flat is deprecated shim)
+  if (moduleFiles.length > 0) {
+    const moduleNames = new Set(moduleFiles.map((f) => f.name));
+    const filteredFlat = flat.filter((f) => !moduleNames.has(f.name));
+    return dedupeByPath([...filteredFlat, ...moduleFiles]);
+  }
+  return dedupeByPath([...flat, ...moduleFiles]);
+}
+
+function dedupeByPath(files: DiscoveredFile[]): DiscoveredFile[] {
+  const seen = new Set<string>();
+  const out: DiscoveredFile[] = [];
+  for (const f of files) if (!seen.has(f.path)) { seen.add(f.path); out.push(f); }
+  return out;
+}
+
 async function collectPluginDirs(dir: string): Promise<DiscoveredFile[]> {
   if (!existsSync(dir)) return [];
   const out: DiscoveredFile[] = [];

package/src/config/defaults.ts

@@ -34,6 +34,10 @@ export const defaults: NexusConfig = {
     federation: 'in-process',
     subscriptions: true,
     introspection: true,
+    explorer: true,
+    hello: true,
+    requireMutationCsrf: true,
+    explorerRequireAuth: false,
   },
   ws: {
     path: '/ws',

package/src/config/runtimeJson.ts

@@ -74,5 +74,11 @@ export async function mergeRuntimeJson(projectRoot: string, patch: Record<string
   if (patch.ai && typeof patch.ai === 'object' && existing.ai && typeof existing.ai === 'object') {
     merged.ai = { ...(existing as { ai: Record<string, unknown> }).ai, ...(patch.ai as Record<string, unknown>) };
   }
+  // Deep-merge `payments` so toggling one provider's enabled/sandbox state does
+  // NOT wipe the other providers' persisted state (shallow merge would replace
+  // the whole payments object).
+  if (patch.payments && typeof patch.payments === 'object' && existing.payments && typeof existing.payments === 'object') {
+    merged.payments = { ...(existing as { payments: Record<string, unknown> }).payments, ...(patch.payments as Record<string, unknown>) };
+  }
   await writeRuntimeJson(projectRoot, stripRedactionMask(merged) as Record<string, unknown>);
 }

package/src/config/schema.ts

@@ -39,6 +39,10 @@ export const nexusConfigSchema = z.object({
     federation: z.enum(['in-process', 'distributed']),
     subscriptions: z.boolean(),
     introspection: z.boolean(),
+    explorer: z.boolean().optional(),
+    hello: z.boolean().optional(),
+    requireMutationCsrf: z.boolean(),
+    explorerRequireAuth: z.boolean().optional(),
   }),
   ws: z.object({
     path: z.string().min(1),

package/src/config/types.ts

@@ -154,6 +154,14 @@ export interface GraphqlConfig {
   subscriptions: boolean;
   /** Introspection enabled (disable in production). */
   introspection: boolean;
+  /** Serve the interactive sandbox at GET /graphiql. */
+  explorer?: boolean;
+  /** Include builtin hello/ping subgraph in every app (default true). Disable with `hello: false`. */
+  hello?: boolean;
+  /** Require a matching CSRF token to execute mutation operations on /graphql (default true). */
+  requireMutationCsrf?: boolean;
+  /** Require an admin access token (JWT) to open the GraphiQL explorer at /graphiql (default false). */
+  explorerRequireAuth?: boolean;
 }
 
 export interface WsConfig {