@bhooai/nexus-graphql 2.0.11 → 2.0.13

package/src/federation/createFederatedGateway.ts

@@ -1,7 +1,7 @@
 import { parse, type DocumentNode, type ExecutionResult } from 'graphql';
 import type { Subgraph, GraphQLContext, ExecuteParams } from '../types.js';
 import { composeSupergraph, type Supergraph } from './composeSupergraph.js';
-import { executeFederated, planQuery, type FetchPlan } from './executor.js';
+import { executeFederated, subscribeFederated, planQuery, type FetchPlan } from './executor.js';
 
 export interface FederatedGateway {
   /** Client-facing merged schema. */
@@ -9,6 +9,7 @@ export interface FederatedGateway {
   supergraph: Supergraph;
   subgraphs: Subgraph[];
   execute(params: Omit<ExecuteParams, 'schema' | 'resolvers'>): Promise<ExecutionResult>;
+  subscribe(params: Omit<ExecuteParams, 'schema' | 'resolvers'>): Promise<AsyncIterable<ExecutionResult> | ExecutionResult>;
   /** Inspect the fetch plan for a query (golden tests / debugging). */
   plan(document: DocumentNode): FetchPlan;
 }
@@ -29,6 +30,10 @@ export function createFederatedGateway(subgraphs: Subgraph[]): FederatedGateway
       const document: DocumentNode = params.document;
       return executeFederated(supergraph, document, params.variableValues, (params.contextValue as GraphQLContext) ?? {});
     },
+    async subscribe(params) {
+      const document: DocumentNode = params.document;
+      return subscribeFederated(supergraph, document, params.variableValues, (params.contextValue as GraphQLContext) ?? {});
+    },
     plan(document) {
       return planQuery(supergraph, document);
     },

package/src/federation/executor.ts

@@ -1,7 +1,14 @@
-import { execute, parse, isObjectType, isInterfaceType, type DocumentNode, type SelectionSetNode, type FieldNode, type InlineFragmentNode, type FragmentSpreadNode, type ExecutionResult } from 'graphql';
+import { execute, subscribe, parse, isObjectType, isInterfaceType, type DocumentNode, type SelectionSetNode, type FieldNode, type InlineFragmentNode, type FragmentSpreadNode, type FragmentDefinitionNode, type ExecutionResult } from 'graphql';
+
+/** Introspection root fields (`__schema`/`__type`) live on the merged schema, not any one subgraph. */
+function isIntrospectionSelection(sel: SelectionSetNode): boolean {
+  return sel.selections.some(
+    (s) => s.kind === 'Field' && (s.name.value === '__schema' || s.name.value === '__type'),
+  );
+}
 import type { Supergraph } from './composeSupergraph.js';
 import type { Subgraph, GraphQLContext } from '../types.js';
-import { createFieldResolver } from '../gateway/fieldResolver.js';
+import { createFieldResolver, createSubscribeFieldResolver } from '../gateway/fieldResolver.js';
 
 /**
  * Naive sequential federated executor (Phase 6, v1).
@@ -67,11 +74,24 @@ export async function executeFederated(
   contextValue: GraphQLContext,
 ): Promise<ExecutionResult> {
   const op = document.definitions.find((d) => d.kind === 'OperationDefinition') as
-    | { selectionSet: SelectionSetNode; operation: string }
+    | { selectionSet: SelectionSetNode; operation: string; variableDefinitions?: readonly { variable?: { name?: { value?: string } } }[] }
     | undefined;
   if (!op) return { errors: [{ message: 'No operation in document' }] as unknown as NonNullable<ExecutionResult['errors']> };
   const rootType = op.operation === 'mutation' ? 'Mutation' : op.operation === 'subscription' ? 'Subscription' : 'Query';
 
+  // Introspection (`__schema`/`__type`) belongs to the merged schema, not a
+  // subgraph — execute it directly against the composed schema so the explorer
+  // Docs panel and standard clients can fetch the full schema.
+  if (isIntrospectionSelection(op.selectionSet)) {
+    return execute({
+      schema: supergraph.schema,
+      document,
+      rootValue: undefined,
+      contextValue,
+      variableValues,
+    }) as Promise<ExecutionResult>;
+  }
+
   const subgraphByName = new Map<string, Subgraph>(supergraph.subgraphs.map((s) => [s.name, s]));
 
   // 1. Root pass: group top-level fields by owner and execute trimmed subqueries.
@@ -89,7 +109,7 @@ export async function executeFederated(
   for (const [subName, fields] of rootGroups) {
     const sub = subgraphByName.get(subName)!;
     const sel = trimSelection(fields, rootType, subName, supergraph, true);
-    const sdl = `${op.operation} { ${sel} }`;
+    const sdl = `${op.operation}${varDefsToSdl(op.variableDefinitions)} { ${sel} }`;
     const res = await execSubgraph(sub, parse(sdl), variableValues, contextValue);
     if (res.errors) return { errors: res.errors };
     Object.assign(data, res.data as Record<string, unknown>);
@@ -127,6 +147,43 @@ async function execSubgraph(sub: Subgraph, document: DocumentNode, variableValue
   });
 }
 
+/**
+ * Execute a federated subscription in-process. Subscriptions are not federated
+ * in v1 — a subscription's root field is owned by exactly one subgraph, so we
+ * route the whole operation to that subgraph and subscribe with its resolvers.
+ */
+export async function subscribeFederated(
+  supergraph: Supergraph,
+  document: DocumentNode,
+  variableValues: Record<string, any> | undefined,
+  contextValue: GraphQLContext,
+): Promise<AsyncIterable<ExecutionResult> | ExecutionResult> {
+  const op = document.definitions.find((d) => d.kind === 'OperationDefinition') as
+    | { selectionSet: SelectionSetNode; operation: string }
+    | undefined;
+  if (!op) return { errors: [{ message: 'No operation in document' }] as unknown as NonNullable<ExecutionResult['errors']> };
+  if (op.operation !== 'subscription') return { errors: [{ message: 'subscribe() only supports subscription operations' }] as unknown as NonNullable<ExecutionResult['errors']> };
+
+  const field = op.selectionSet.selections.find((s) => s.kind === 'Field') as FieldNode | undefined;
+  if (!field) return { errors: [{ message: 'No subscription field found' }] as unknown as NonNullable<ExecutionResult['errors']> };
+
+  const owner = supergraph.ownership.get('Subscription')?.get(field.name.value);
+  if (!owner) return { errors: [{ message: `No subgraph owns Subscription.${field.name.value}` }] as unknown as NonNullable<ExecutionResult['errors']> };
+
+  const sub = supergraph.subgraphs.find((s) => s.name === owner);
+  if (!sub) return { errors: [{ message: `Subgraph "${owner}" not found` }] as unknown as NonNullable<ExecutionResult['errors']> };
+
+  return subscribe({
+    schema: sub.schema,
+    document,
+    rootValue: undefined,
+    contextValue,
+    variableValues,
+    subscribeFieldResolver: createSubscribeFieldResolver(sub.resolvers),
+    fieldResolver: createFieldResolver(sub.resolvers),
+  }) as Promise<AsyncIterable<ExecutionResult> | ExecutionResult>;
+}
+
 /** Unwrap a GraphQL type name to its base named type. */
 function baseType(type: string): string {
   return type.replace(/[\[\]!]/g, '');
@@ -187,9 +244,27 @@ function trimSelection(selections: readonly (FieldNode | InlineFragmentNode | Fr
   return parts.join(' ');
 }
 
+/** Serialize a document's variable definitions back to SDL, e.g. `($id: ID!, $title: String!)`. */
+function varDefsToSdl(defs: readonly { variable?: { name?: { value?: string } }; type?: import('graphql').TypeNode; defaultValue?: import('graphql').ConstValueNode }[] | undefined): string {
+  if (!defs || defs.length === 0) return '';
+  const parts = defs.map((d) => {
+    const name = d.variable?.name?.value;
+    if (!name || !d.type) return '';
+    return `$${name}: ${typeToSdl(d.type)}${d.defaultValue !== undefined ? ` = ${valueToSdl(d.defaultValue)}` : ''}`;
+  }).filter(Boolean);
+  return parts.length ? `(${parts.join(', ')})` : '';
+}
+function typeToSdl(t: import('graphql').TypeNode): string {
+  switch (t.kind) {
+    case 'NamedType': return t.name.value;
+    case 'ListType': return `[${typeToSdl(t.type)}]`;
+    case 'NonNullType': return `${typeToSdl(t.type)}!`;
+    default: return '';
+  }
+}
+
 /** Serialize a field's arguments to SDL, e.g. `(id: "u1", limit: $limit)`. */
-function argsToSdl(args: readonly import('graphql').ArgumentNode[] | undefined): string {
-  if (!args || args.length === 0) return '';
+function argsToSdl(args: readonly import('graphql').ArgumentNode[] | undefined): string {  if (!args || args.length === 0) return '';
   return '(' + args.map((a) => `${a.name.value}: ${valueToSdl(a.value)}`).join(', ') + ')';
 }
 function valueToSdl(v: import('graphql').ValueNode): string {

package/src/federation/parseMetadata.ts

@@ -64,17 +64,19 @@ function balancedBody(s: string, start: number): string {
 /** Parse field definitions in a type body into name → FieldMeta. */
 function parseFields(body: string): Map<string, FieldMeta> {
   const out = new Map<string, FieldMeta>();
-  // Each field line roughly: `name(args): Type <directives>` separated by newlines.
-  // We scan line-ish fragments split on top-level commas/newlines.
-  const lines = body.split('\n').map((l) => l.trim()).filter(Boolean);
-  for (const line of lines) {
-    // Strip leading modifiers; capture field name as the first identifier.
-    const nameMatch = /^(\w+)/.exec(line);
-    if (!nameMatch) continue;
-    const name = nameMatch[1]!;
-    const external = /@external\b/.test(line);
-    const provides = matchFields(line, '@provides');
-    const requires = matchFields(line, '@requires');
+  // A field is `name(args)?: Type <directives>` — a type like `[String!]!` never
+  // contains `@`, so a field run ends when the next field name (before its `:`)
+  // begins. Scanning with a regex (rather than splitting on newlines) handles
+  // bodies that pack many fields onto one line, e.g.
+  //   type Message @key(fields: "id") { id: ID! roomId: String! text: String! }
+  const fieldRe = /(\w+)\s*(?:\([^)]*\))?\s*:\s*[\w\[\]!()]+\s*(?:@\w+(?:\s*\([^)]*\))?)*/g;
+  let m: RegExpExecArray | null;
+  while ((m = fieldRe.exec(body)) !== null) {
+    const name = m[1]!;
+    const text = m[0];
+    const external = /@external\b/.test(text);
+    const provides = matchFields(text, '@provides');
+    const requires = matchFields(text, '@requires');
     out.set(name, { external, provides, requires });
   }
   return out;

package/src/gateway/graphqlHttpHandler.ts

@@ -1,6 +1,7 @@
-import { parse, type DocumentNode } from 'graphql';
+import { parse, type DocumentNode, type OperationDefinitionNode } from 'graphql';
 import type { RequestContext, Handler } from '@bhooai/nexus-core';
 import type { Gateway, GraphQLContext } from '../types.js';
+import { verifyMutationCsrf } from '@bhooai/nexus-auth';
 
 export interface GraphqlHandlerOptions {
   /** The gateway to execute against. */
@@ -9,12 +10,23 @@ export interface GraphqlHandlerOptions {
   context?: (ctx: RequestContext) => GraphQLContext | Promise<GraphQLContext>;
   /** Allow introspection queries (default follows config.graphql.introspection = true). */
   introspection?: boolean;
+  /** Require a matching CSRF token to execute mutations (default true). The token may be sent via the `X-CSRF-Token` header or a `csrf` argument, and must match the double-submit cookie. Obtain it from GET /csrf-token or the GraphQL `csrfToken` query. */
+  requireMutationCsrf?: boolean;
 }
 
 interface GraphQLRequestBody {
   query?: string;
   variables?: Record<string, any>;
   operationName?: string;
+  csrf?: string;
+}
+
+/** True when any operation in the document is a mutation. */
+function hasMutationOperation(doc: DocumentNode): boolean {
+  for (const def of doc.definitions) {
+    if (def.kind === 'OperationDefinition' && (def as OperationDefinitionNode).operation === 'mutation') return true;
+  }
+  return false;
 }
 
 /** True when a parsed operation set contains an introspection field (`__schema`/`__type`). */
@@ -33,15 +45,16 @@ function isIntrospectionDocument(doc: DocumentNode): boolean {
 /**
  * HTTP handler for `/graphql`. Accepts POST with `{ query, variables, operationName }`
  * (or GET with `?query=`). Applies the gateway in-process. Introspection is
- * rejected when disabled.
+ * rejected when disabled. Mutations additionally require a CSRF token (via the
+ * `X-CSRF-Token` header or a `csrf` argument) that matches the double-submit cookie.
  */
 export function graphqlHttpHandler(options: GraphqlHandlerOptions): Handler {
-  const { gateway, introspection = true } = options;
+  const { gateway, introspection = true, requireMutationCsrf = true } = options;
   return async (ctx: RequestContext) => {
     let body: GraphQLRequestBody;
     if (ctx.method === 'GET') {
       const q = ctx.query.query;
-      body = { query: Array.isArray(q) ? q[0] : q, variables: parseJsonQuery(ctx.query.variables), operationName: single(ctx.query.operationName) };
+      body = { query: Array.isArray(q) ? q[0] : q, variables: parseJsonQuery(ctx.query.variables), operationName: single(ctx.query.operationName), csrf: single(ctx.query.csrf) };
     } else {
       body = (ctx.body as GraphQLRequestBody) ?? {};
     }
@@ -64,6 +77,20 @@ export function graphqlHttpHandler(options: GraphqlHandlerOptions): Handler {
       return;
     }
 
+    // Mutations are unsafe: require a matching CSRF token equal to the double-submit
+    // cookie. The token may arrive as an argument (body.csrf, variables.csrf, GET
+    // ?csrf=) OR in the X-CSRF-Token header — either channel matching the cookie passes.
+    if (requireMutationCsrf && hasMutationOperation(document)) {
+      const headerToken = single(ctx.headers['x-csrf-token'] as string | string[] | undefined);
+      const argToken =
+        body.csrf ??
+        (body.variables && typeof body.variables === 'object' ? (body.variables as Record<string, unknown>).csrf as string : undefined);
+      if (!verifyMutationCsrf(ctx, argToken, headerToken)) {
+        ctx.json({ errors: [{ message: 'Invalid CSRF token: required for mutations.' }] }, 403);
+        return;
+      }
+    }
+
     const contextValue = options.context
       ? await options.context(ctx)
       : { request: ctx, user: (ctx.state.user as GraphQLContext['user']) };

package/src/index.ts

@@ -1,7 +1,9 @@
 export * from './types.js';
+export * from './mutationCsrf.js';
 export * from './subgraph/federationDirectives.js';
 export * from './subgraph/parseKeys.js';
 export * from './subgraph/defineSubgraph.js';
+export * from './explorer/explorerHtml.js';
 export * from './gateway/fieldResolver.js';
 export * from './gateway/publicSchema.js';
 export * from './gateway/createGateway.js';
@@ -11,4 +13,5 @@ export * from './subscriptions/SubscriptionServer.js';
 export * from './federation/parseMetadata.js';
 export * from './federation/composeSupergraph.js';
 export * from './federation/executor.js';
-export * from './federation/createFederatedGateway.js';
+export * from './federation/createFederatedGateway.js';
+export * from './builtin/helloSubgraph.js';

package/src/mutationCsrf.ts

@@ -0,0 +1,25 @@
+import type { GraphQLContext } from './types.js';
+import { verifyMutationCsrf } from '@bhooai/nexus-auth';
+
+/**
+ * Validate a mutation's CSRF token against the request's double-submit cookie.
+ * The token may be passed as the `csrfToken` argument or in the `X-CSRF-Token`
+ * header — either channel matching the cookie passes. Throws when missing or
+ * mismatched, so per-mutation resolvers can gate writes explicitly (defense-in-depth
+ * on top of the HTTP-level enforcement).
+ */
+export function assertMutationCsrf(context: GraphQLContext, csrfToken: string | undefined): void {
+  const ctx = context?.request as
+    | { headers?: Record<string, string | string[] | undefined> }
+    | undefined;
+  if (!ctx) throw new Error('Invalid CSRF token: required for this mutation.');
+  const headerToken =
+    ctx.headers?.['x-csrf-token'] !== undefined
+      ? Array.isArray(ctx.headers['x-csrf-token'])
+        ? (ctx.headers['x-csrf-token'] as string[])[0]
+        : (ctx.headers['x-csrf-token'] as string)
+      : undefined;
+  if (!verifyMutationCsrf(ctx as Parameters<typeof verifyMutationCsrf>[0], csrfToken, headerToken)) {
+    throw new Error('Invalid CSRF token: required for this mutation.');
+  }
+}