@nifrajs/graphql 3.2.0

package/README.md

@@ -0,0 +1,119 @@
+# @nifrajs/graphql
+
+Mount a GraphQL endpoint on a nifra app. A spec-compliant [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/) handler, `graphql-transport-ws` subscriptions over nifra's native WebSocket lane, and your typed nifra context piped straight into resolvers.
+
+It executes with the `graphql` package's own `parse`/`validate`/`execute`/`subscribe` - no HTTP framework is re-bundled, the request body reuses core's single bounded, prototype-guarded trust boundary, and the query text is never logged.
+
+## Install
+
+```bash
+bun add @nifrajs/graphql graphql
+# subscriptions also need:
+bun add graphql-ws
+```
+
+`graphql` is a required peer; `graphql-ws` is optional (only for subscriptions).
+
+## Queries and mutations
+
+```ts
+import { server } from "@nifrajs/core"
+import { mountGraphql } from "@nifrajs/graphql"
+import { buildSchema } from "graphql"
+
+const schema = buildSchema(`
+  type Query { hello: String }
+  type Mutation { echo(msg: String!): String }
+`)
+
+const rootValue = {
+  hello: () => "world",
+  echo: ({ msg }: { msg: string }) => msg,
+}
+
+const app = server()
+mountGraphql(app, { schema, rootValue })
+// POST /graphql  - queries + mutations
+// GET  /graphql  - queries only (idempotent, cacheable)
+```
+
+Prefer the handler directly? Mount it yourself:
+
+```ts
+import { respondGraphql } from "@nifrajs/graphql"
+
+app.post("/graphql", (c) => respondGraphql(c.req, { schema, rootValue }))
+```
+
+## Context injection
+
+The one thing a plain third-party mount cannot do: derive the resolver `contextValue` from what your nifra handler already resolved (auth subject, env, params).
+
+```ts
+mountGraphql(app, {
+  schema,
+  context: ({ request, nifra }) => ({
+    user: nifra?.env,           // nifra route context, when mounted via mountGraphql
+    ip: request.headers.get("x-forwarded-for"),
+  }),
+})
+```
+
+Resolvers read it as their third argument.
+
+## Subscriptions
+
+Subscriptions run over the same route via `graphql-transport-ws`. Bring a subscription source - the bundled in-memory `createPubSub` is the reference implementation; swap in a durable bus (Redis, a Durable Object, NATS) that exposes the same `{ publish, subscribe }` shape for multi-instance deploys.
+
+```ts
+import { server } from "@nifrajs/core"
+import { websocket } from "@nifrajs/core/ws"
+import { mountGraphql, createPubSub } from "@nifrajs/graphql"
+
+const pubsub = createPubSub<number>()
+
+const app = server().use(websocket())
+mountGraphql(app, {
+  schema,
+  context: () => ({ pubsub }),
+  subscriptions: true,
+})
+
+// A resolver:
+//   count: { subscribe: (_, __, ctx) => ctx.pubsub.subscribe("count"), resolve: (n) => n }
+// Push an event from anywhere:
+pubsub.publish("count", 1)
+```
+
+The route must negotiate the `graphql-transport-ws` subprotocol at the WebSocket layer for a browser `graphql-ws` client to connect.
+
+## Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `schema` | - | Executable `GraphQLSchema` (required). |
+| `context` | `{}` | Build the resolver `contextValue` per operation. |
+| `rootValue` | - | Root value passed to the executor. |
+| `maxBodyBytes` | `1_000_000` | Request body cap; larger bodies answer 413. |
+| `protoPoisoning` | `"reject"` | Prototype-pollution policy for the JSON body. |
+| `allowedOrigins` | reflect `*` | CORS origin allowlist. |
+| `authorize` | - | Per-request guard; return `false` for 401. |
+| `enableGet` | `true` | Serve `GET /graphql` (queries only). |
+| `subscriptions` | `false` | `true` (reuse schema/context) or explicit WS options. |
+| `legacyJsonResponse` | `false` | Old always-200 `application/json` shape. |
+
+## Responses
+
+By default responses use the `application/graphql-response+json` media type with spec status codes: `200` for an executed result (including field errors in `errors`), `400` for a parse or validation failure, `401` for a rejected `authorize`, `405` for a mutation attempted over GET. Set `legacyJsonResponse: true` for the older always-`200` `application/json` behavior some clients expect.
+
+## License
+
+MIT
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.

package/dist/context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The context-injection seam - the one thing a hand-rolled `app.all('/graphql', yoga.fetch)` mount
+ * cannot do. A GraphQL executor builds an opaque `contextValue` from the raw `Request`; it never sees
+ * the nifra request context (auth subject, params, env, `waitUntil`). This contract lets a resolver's
+ * `contextValue` be derived from whatever the surrounding nifra handler already resolved.
+ *
+ * The builder is called once per operation (per HTTP request, or once per WS `Subscribe` message),
+ * before `execute`/`subscribe`. It receives the raw `Request` and, on the HTTP path, the nifra route
+ * context `c` when the endpoint is mounted with `mountGraphql` (which has `c` in scope); on the WS path
+ * it receives the upgrade request. Return the object your resolvers read as their third argument.
+ *
+ * MOAT NOTE: this seam only *passes through* context the host already owns. It never persists it. A
+ * tenant-aware or durable resolver-context store is an operated concern and lives outside this package.
+ */
+/** What the builder is handed. `request` is always present; `nifra` is the route context when known. */
+export interface GraphqlContextInput<Env = unknown> {
+    readonly request: Request;
+    /**
+     * The nifra route context (`c`) when the endpoint was mounted via `mountGraphql`, otherwise
+     * `undefined` (e.g. `respondGraphql` called standalone, or the WS transport before a route context
+     * exists). Typed loosely on purpose so this package never imports core's context type at the value
+     * level - keeping the peer dependency truly optional.
+     */
+    readonly nifra?: NifraContextLike<Env>;
+}
+/**
+ * The subset of a nifra route context this package surfaces to a resolver-context builder. Structural,
+ * so the real `c` satisfies it without a nominal import. Kept to the non-body accessors a resolver
+ * legitimately needs; the raw body belongs to the GraphQL executor, not the builder.
+ */
+export interface NifraContextLike<Env = unknown> {
+    readonly req: Request;
+    readonly params: Record<string, string>;
+    readonly env: Env;
+    readonly signal: AbortSignal;
+    readonly waitUntil: (promise: Promise<unknown>) => void;
+}
+/**
+ * Build the resolver `contextValue` for one operation. Sync or async; a throw is reported as a GraphQL
+ * error envelope rather than crashing the transport. Omit it and resolvers get `contextValue: {}`.
+ */
+export type GraphqlContextBuilder<Context = unknown, Env = unknown> = (input: GraphqlContextInput<Env>) => Context | Promise<Context>;
+/** Resolve a context builder to a concrete value, defaulting to an empty object. */
+export declare function buildContext<Context, Env>(builder: GraphqlContextBuilder<Context, Env> | undefined, input: GraphqlContextInput<Env>): Promise<Context>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wGAAwG;AACxG,MAAM,WAAW,mBAAmB,CAAC,GAAG,GAAG,OAAO;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAA;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,GAAG,GAAG,OAAO;IAC7C,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IACjB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;CACxD;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,OAAO,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI,CACpE,KAAK,EAAE,mBAAmB,CAAC,GAAG,CAAC,KAC5B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAE/B,oFAAoF;AACpF,wBAAsB,YAAY,CAAC,OAAO,EAAE,GAAG,EAC7C,OAAO,EAAE,qBAAqB,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,SAAS,EACxD,KAAK,EAAE,mBAAmB,CAAC,GAAG,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/context.js

@@ -0,0 +1,21 @@
+/**
+ * The context-injection seam - the one thing a hand-rolled `app.all('/graphql', yoga.fetch)` mount
+ * cannot do. A GraphQL executor builds an opaque `contextValue` from the raw `Request`; it never sees
+ * the nifra request context (auth subject, params, env, `waitUntil`). This contract lets a resolver's
+ * `contextValue` be derived from whatever the surrounding nifra handler already resolved.
+ *
+ * The builder is called once per operation (per HTTP request, or once per WS `Subscribe` message),
+ * before `execute`/`subscribe`. It receives the raw `Request` and, on the HTTP path, the nifra route
+ * context `c` when the endpoint is mounted with `mountGraphql` (which has `c` in scope); on the WS path
+ * it receives the upgrade request. Return the object your resolvers read as their third argument.
+ *
+ * MOAT NOTE: this seam only *passes through* context the host already owns. It never persists it. A
+ * tenant-aware or durable resolver-context store is an operated concern and lives outside this package.
+ */
+/** Resolve a context builder to a concrete value, defaulting to an empty object. */
+export async function buildContext(builder, input) {
+    if (builder === undefined)
+        return {};
+    return await builder(input);
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmCH,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAwD,EACxD,KAA+B;IAE/B,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAa,CAAA;IAC/C,OAAO,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7B,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The GraphQL-over-HTTP transport - a plain Web `fetch` handler you mount at `POST /graphql` (and
+ * optionally `GET /graphql`). It parses, validates, and executes against your `GraphQLSchema` using
+ * `graphql`'s own `parse`/`validate`/`execute`; no server framework is re-bundled and no second HTTP
+ * trust boundary is created - the request body is read through core's one bounded/proto-guarded lane
+ * (`@nifrajs/core/edge-kit`'s {@link readBodyFramed}).
+ *
+ * Spec: https://graphql.github.io/graphql-over-http/draft/. POST carries `{query, operationName?,
+ * variables?, extensions?}` as `application/json`; GET carries them as query-string params and may run
+ * **queries only** (never a mutation) so it stays a safe, cacheable idempotent method. Responses use the
+ * `application/graphql-response+json` media type with spec status codes by default; set
+ * `legacyJsonResponse` for the old always-200 `application/json` shape older clients expect.
+ *
+ * PRIVACY: the handler never logs the query text, variables, or the request body. GraphQL documents are
+ * user payloads; keeping them out of this package's output is the guardrail (a payload sink is an
+ * operated concern, not a public-package one).
+ */
+import { type ProtoPoisoning } from "@nifrajs/core/edge-kit";
+import { type GraphQLSchema } from "graphql";
+import { type GraphqlContextBuilder, type NifraContextLike } from "./context.js";
+export interface GraphqlHttpOptions<Context = unknown, Env = unknown> {
+    /** The executable schema (types + resolvers), e.g. from `graphql`'s `buildSchema` or a schema builder. */
+    readonly schema: GraphQLSchema;
+    /** Build the resolver `contextValue` from the request (and nifra context when mounted). */
+    readonly context?: GraphqlContextBuilder<Context, Env>;
+    /** The nifra route context, when the caller has one (supplied by `mountGraphql`). */
+    readonly nifra?: NifraContextLike<Env>;
+    /** Maximum request body size in bytes. Default 1 MB. Rejected bodies answer 413. */
+    readonly maxBodyBytes?: number;
+    /** Prototype-pollution policy for the parsed JSON body. Default `"reject"`. */
+    readonly protoPoisoning?: ProtoPoisoning;
+    /** Optional root value passed to the executor. */
+    readonly rootValue?: unknown;
+    /**
+     * Origin allowlist for the CORS `access-control-allow-origin` header. Omit to reflect any origin
+     * (`*`) - correct for a public API; set it to lock the browser callers down.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /**
+     * Per-request authorization, run after the body parses and before execution. Return `false` to answer
+     * `401` with a GraphQL error envelope and skip execution entirely.
+     */
+    readonly authorize?: (request: Request) => boolean | Promise<boolean>;
+    /** Emit the legacy always-200 `application/json` response shape instead of `application/graphql-response+json`. */
+    readonly legacyJsonResponse?: boolean;
+}
+/**
+ * Handle one GraphQL HTTP request. Never throws - a malformed request becomes a GraphQL error envelope.
+ * Mount it directly (`app.all('/graphql', (c) => respondGraphql(c.req, { schema }))`) or via
+ * {@link mountGraphql}, which also wires the nifra context in.
+ */
+export declare function respondGraphql<Context = unknown, Env = unknown>(request: Request, options: GraphqlHttpOptions<Context, Env>): Promise<Response>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,cAAc,EAOpB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAKL,KAAK,aAAa,EAMnB,MAAM,SAAS,CAAA;AAChB,OAAO,EAEL,KAAK,qBAAqB,EAE1B,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAA;AAYrB,MAAM,WAAW,kBAAkB,CAAC,OAAO,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO;IAClE,0GAA0G;IAC1G,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;IACtD,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAA;IACtC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;IACxC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrE,mHAAmH;IACnH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CACtC;AAqKD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,EACnE,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,kBAAkB,CAAC,OAAO,EAAE,GAAG,CAAC,GACxC,OAAO,CAAC,QAAQ,CAAC,CA+DnB"}

package/dist/http.js

@@ -0,0 +1,221 @@
+/**
+ * The GraphQL-over-HTTP transport - a plain Web `fetch` handler you mount at `POST /graphql` (and
+ * optionally `GET /graphql`). It parses, validates, and executes against your `GraphQLSchema` using
+ * `graphql`'s own `parse`/`validate`/`execute`; no server framework is re-bundled and no second HTTP
+ * trust boundary is created - the request body is read through core's one bounded/proto-guarded lane
+ * (`@nifrajs/core/edge-kit`'s {@link readBodyFramed}).
+ *
+ * Spec: https://graphql.github.io/graphql-over-http/draft/. POST carries `{query, operationName?,
+ * variables?, extensions?}` as `application/json`; GET carries them as query-string params and may run
+ * **queries only** (never a mutation) so it stays a safe, cacheable idempotent method. Responses use the
+ * `application/graphql-response+json` media type with spec status codes by default; set
+ * `legacyJsonResponse` for the old always-200 `application/json` shape older clients expect.
+ *
+ * PRIVACY: the handler never logs the query text, variables, or the request body. GraphQL documents are
+ * user payloads; keeping them out of this package's output is the guardrail (a payload sink is an
+ * operated concern, not a public-package one).
+ */
+import { EMPTY_RESPONSE_CONTROLS, plainError, queryObjectOf, readBodyFramed, searchOf, toResponse, } from "@nifrajs/core/edge-kit";
+import { execute, GraphQLError, getOperationAST, parse, Source, specifiedRules, validate, } from "graphql";
+import { buildContext, } from "./context.js";
+const DEFAULT_MAX_BODY_BYTES = 1_000_000;
+const GRAPHQL_RESPONSE_JSON = "application/graphql-response+json; charset=utf-8";
+const JSON_UTF8 = "application/json; charset=utf-8";
+const CORS_BASE = {
+    "access-control-allow-methods": "GET, POST, OPTIONS",
+    "access-control-allow-headers": "content-type, authorization",
+    "access-control-max-age": "86400",
+};
+function assertByteLimit(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError("GraphQL maxBodyBytes must be a non-negative safe integer");
+    }
+}
+function corsFor(request, allowedOrigins) {
+    if (allowedOrigins === undefined)
+        return { ...CORS_BASE, "access-control-allow-origin": "*" };
+    const origin = request.headers.get("origin");
+    if (origin === null)
+        return { ...CORS_BASE, vary: "Origin" };
+    if (allowedOrigins.includes(origin)) {
+        return { ...CORS_BASE, "access-control-allow-origin": origin, vary: "Origin" };
+    }
+    return null;
+}
+/** Render a rejection from readBodyFramed - a `Response` passes through, a `ResponseResult` is rendered
+ * through the same core renderer the full Server uses, so the wire bytes match. */
+function render(r) {
+    return r instanceof Response ? r : toResponse(r, EMPTY_RESPONSE_CONTROLS);
+}
+/** Serialize an execution/error payload to a JSON `Response` with the negotiated media type + status.
+ * `payload` is any JSON-serializable GraphQL result (`{data?, errors?}`); GraphQLError values serialize
+ * via their own `toJSON`. */
+function graphqlResponse(payload, status, legacy, cors) {
+    return new Response(JSON.stringify(payload), {
+        status: legacy ? 200 : status,
+        headers: { "content-type": legacy ? JSON_UTF8 : GRAPHQL_RESPONSE_JSON, ...cors },
+    });
+}
+/** A request-level (parse/validate/auth/method) failure: `{ errors: [...] }`, no `data` key. */
+function requestError(message, status, legacy, cors, errors) {
+    const payload = errors ?? [new GraphQLError(message)];
+    return graphqlResponse({ errors: payload.map((e) => e.toJSON()) }, status, legacy, cors);
+}
+/** Coerce a `?variables=<json>` string (GET) into an object, or throw a GraphQLError on bad JSON. */
+function parseVariables(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (typeof raw === "object")
+        return raw;
+    if (typeof raw !== "string")
+        throw new GraphQLError("Variables must be a JSON object.");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new GraphQLError("Variables are invalid JSON.");
+    }
+    if (parsed === null)
+        return null;
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new GraphQLError("Variables must be a JSON object.");
+    }
+    return parsed;
+}
+/** Read `{query, operationName, variables}` from a parsed POST body. Throws GraphQLError when malformed. */
+function paramsFromBody(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new GraphQLError("POST body must be a JSON object.");
+    }
+    const b = body;
+    if (typeof b.query !== "string" || b.query.length === 0) {
+        throw new GraphQLError("A `query` string is required.");
+    }
+    const operationName = typeof b.operationName === "string" ? b.operationName : null;
+    return { query: b.query, operationName, variables: parseVariables(b.variables) };
+}
+/** Read the same shape from a GET query string. */
+function paramsFromQuery(query) {
+    const q = query.query;
+    if (typeof q !== "string" || q.length === 0)
+        throw new GraphQLError("A `query` parameter is required.");
+    const operationName = typeof query.operationName === "string" ? query.operationName : null;
+    return { query: q, operationName, variables: parseVariables(query.variables) };
+}
+/** Parse, validate, and execute one already-extracted GraphQL request. */
+async function run(params, request, opts, isGet, legacy, cors) {
+    let document;
+    try {
+        document = parse(new Source(params.query, "GraphQL request"));
+    }
+    catch (err) {
+        const gqlErr = err instanceof GraphQLError ? err : new GraphQLError(String(err));
+        return requestError("", 400, legacy, cors, [gqlErr]);
+    }
+    const validationErrors = validate(opts.schema, document, specifiedRules);
+    if (validationErrors.length > 0) {
+        return requestError("", 400, legacy, cors, validationErrors);
+    }
+    // GET is idempotent and cacheable, so per the GraphQL-over-HTTP spec it may run queries only.
+    const operationAst = getOperationAST(document, params.operationName ?? undefined);
+    if (isGet && operationAst != null && operationAst.operation !== "query") {
+        return requestError("Only query operations may run over GET.", 405, legacy, { ...cors, allow: "POST" }, [new GraphQLError("Only query operations are allowed over GET.")]);
+    }
+    const contextInput = opts.nifra !== undefined ? { request, nifra: opts.nifra } : { request };
+    let contextValue;
+    try {
+        contextValue = await buildContext(opts.context, contextInput);
+    }
+    catch (err) {
+        const gqlErr = err instanceof GraphQLError ? err : new GraphQLError("Failed to build request context.");
+        return graphqlResponse({ errors: [gqlErr.toJSON()] }, 500, legacy, cors);
+    }
+    let result;
+    try {
+        result = (await execute({
+            schema: opts.schema,
+            document,
+            rootValue: opts.rootValue,
+            contextValue,
+            variableValues: params.variables ?? undefined,
+            operationName: params.operationName ?? undefined,
+        }));
+    }
+    catch (err) {
+        const gqlErr = err instanceof GraphQLError ? err : new GraphQLError("Execution failed.");
+        return graphqlResponse({ errors: [gqlErr.toJSON()] }, 400, legacy, cors);
+    }
+    // Field/execution errors are a normal 200 result with both `data` and `errors`.
+    return graphqlResponse(result, 200, legacy, cors);
+}
+/**
+ * Handle one GraphQL HTTP request. Never throws - a malformed request becomes a GraphQL error envelope.
+ * Mount it directly (`app.all('/graphql', (c) => respondGraphql(c.req, { schema }))`) or via
+ * {@link mountGraphql}, which also wires the nifra context in.
+ */
+export async function respondGraphql(request, options) {
+    const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    assertByteLimit(maxBytes);
+    const legacy = options.legacyJsonResponse === true;
+    const cors = corsFor(request, options.allowedOrigins);
+    if (cors === null)
+        return new Response(null, { status: 403 });
+    if (request.method === "OPTIONS")
+        return new Response(null, { status: 204, headers: cors });
+    if (options.authorize !== undefined) {
+        const ok = await options.authorize(request);
+        if (!ok) {
+            return requestError("Unauthorized.", 401, legacy, cors, [new GraphQLError("Unauthorized.")]);
+        }
+    }
+    if (request.method === "GET") {
+        let params;
+        try {
+            params = paramsFromQuery(queryObjectOf(searchOf(request.url)));
+        }
+        catch (err) {
+            const gqlErr = err instanceof GraphQLError ? err : new GraphQLError(String(err));
+            return requestError("", 400, legacy, cors, [gqlErr]);
+        }
+        return run(params, request, options, true, legacy, cors);
+    }
+    if (request.method !== "POST") {
+        return requestError("Method not allowed.", 405, legacy, { ...cors, allow: "GET, POST" }, [
+            new GraphQLError("Only GET and POST are supported."),
+        ]);
+    }
+    // Read the JSON body through core's single bounded + proto-guarded framing lane.
+    return readBodyFramed(request, maxBytes, options.protoPoisoning ?? "reject", async (parsed) => {
+        let params;
+        try {
+            params = paramsFromBody(parsed);
+        }
+        catch (err) {
+            const gqlErr = err instanceof GraphQLError ? err : new GraphQLError(String(err));
+            return requestError("", 400, legacy, cors, [gqlErr]);
+        }
+        return run(params, request, options, false, legacy, cors);
+    }, (response) => {
+        // readBodyFramed's own rejections (413 too-large, 415, proto-guard) - render + attach CORS.
+        const res = render(response);
+        for (const [k, v] of Object.entries(cors))
+            res.headers.set(k, v);
+        return res;
+    }, (err) => {
+        // A body that failed to read (bad JSON / proto-guard) is a request error, not a crash.
+        if (err instanceof Response)
+            return err;
+        return requestError("Invalid request body.", 400, legacy, cors, [
+            new GraphQLError("Request body could not be read as JSON."),
+        ]);
+    }).catch(() => plainErrorResponse(cors));
+}
+/** Last-resort framing fallback so the handler contract ("never throws") holds even on an edge-kit change. */
+function plainErrorResponse(cors) {
+    const res = render(plainError(400, "bad_request"));
+    for (const [k, v] of Object.entries(cors))
+        res.headers.set(k, v);
+    return res;
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `@nifrajs/graphql` - mount a GraphQL endpoint on a nifra app.
+ *
+ * - {@link respondGraphql} (`./http.ts`) - a spec-compliant GraphQL-over-HTTP `fetch` handler.
+ * - {@link graphqlWebSocket} (`./ws.ts`) - `graphql-transport-ws` subscriptions over `app.ws()`.
+ * - {@link createPubSub} (`./pubsub.ts`) - an in-memory subscription source; swap for a durable bus.
+ * - {@link mountGraphql} - the one-call sugar that wires POST/GET (and, optionally, subscriptions).
+ *
+ * It executes with `graphql`'s own `parse`/`validate`/`execute`/`subscribe`; no HTTP framework is
+ * re-bundled, the request body reuses core's single bounded trust boundary, and the query text is never
+ * logged. `graphql` is a required peer; `graphql-ws` is optional (needed only for subscriptions).
+ */
+import type { NifraContextLike } from "./context.js";
+import { type GraphqlHttpOptions } from "./http.js";
+import { type GraphqlWsOptions } from "./ws.js";
+export type { GraphqlContextBuilder, GraphqlContextInput, NifraContextLike, } from "./context.js";
+export { buildContext } from "./context.js";
+export { type GraphqlHttpOptions, respondGraphql } from "./http.js";
+export { createPubSub, type GraphqlPubSub } from "./pubsub.js";
+export { type GraphqlWsOptions, graphqlWebSocket } from "./ws.js";
+/** The structural slice of a nifra server `mountGraphql` needs. Kept loose so core stays a peer dep. */
+interface RouteContextLike<Env = unknown> extends NifraContextLike<Env> {
+    readonly req: Request;
+}
+interface MountableApp<Env = unknown> {
+    get(path: string, handler: (c: RouteContextLike<Env>) => Response | Promise<Response>): unknown;
+    post(path: string, handler: (c: RouteContextLike<Env>) => Response | Promise<Response>): unknown;
+    ws?(path: string, handler: unknown): unknown;
+}
+export interface MountGraphqlOptions<Context = unknown, Env = unknown> extends Omit<GraphqlHttpOptions<Context, Env>, "nifra"> {
+    /** Endpoint path. Default `/graphql`. */
+    readonly path?: string;
+    /** Enable `GET /graphql` (queries only). Default `true`. */
+    readonly enableGet?: boolean;
+    /**
+     * Enable `graphql-transport-ws` subscriptions on the same path. Pass the WS options (or `true` to
+     * reuse `schema`/`context`). Requires the app to have `.use(websocket())` and `graphql-ws` installed.
+     */
+    readonly subscriptions?: boolean | GraphqlWsOptions<Record<string, unknown>>;
+}
+/**
+ * Mount a GraphQL endpoint. Wires `POST` (and `GET`, unless disabled) on `path`, injecting the nifra
+ * route context into your resolver context, and - when `subscriptions` is set - a `graphql-ws` WebSocket
+ * on the same path.
+ *
+ * ```ts
+ * import { server } from "@nifrajs/core"
+ * import { websocket } from "@nifrajs/core/ws"
+ * import { mountGraphql, createPubSub } from "@nifrajs/graphql"
+ *
+ * const pubsub = createPubSub()
+ * const app = server().use(websocket())
+ * mountGraphql(app, {
+ *   schema,
+ *   context: ({ nifra }) => ({ user: nifra?.env, pubsub }),
+ *   subscriptions: true,
+ * })
+ * ```
+ */
+export declare function mountGraphql<Context = unknown, Env = unknown>(app: MountableApp<Env>, options: MountGraphqlOptions<Context, Env>): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAyB,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC3E,OAAO,EAAE,KAAK,kBAAkB,EAAkB,MAAM,WAAW,CAAA;AACnE,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,SAAS,CAAA;AAEjE,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,KAAK,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AACnE,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,KAAK,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAEjE,wGAAwG;AACxG,UAAU,gBAAgB,CAAC,GAAG,GAAG,OAAO,CAAE,SAAQ,gBAAgB,CAAC,GAAG,CAAC;IACrE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;CACtB;AAED,UAAU,YAAY,CAAC,GAAG,GAAG,OAAO;IAClC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAA;IAC/F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAA;IAChG,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAA;CAC7C;AAED,MAAM,WAAW,mBAAmB,CAAC,OAAO,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,CACnE,SAAQ,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC;IACvD,yCAAyC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAC7E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO,EAC3D,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,EACtB,OAAO,EAAE,mBAAmB,CAAC,OAAO,EAAE,GAAG,CAAC,GACzC,IAAI,CA0BN"}

package/dist/index.js

@@ -0,0 +1,61 @@
+/**
+ * `@nifrajs/graphql` - mount a GraphQL endpoint on a nifra app.
+ *
+ * - {@link respondGraphql} (`./http.ts`) - a spec-compliant GraphQL-over-HTTP `fetch` handler.
+ * - {@link graphqlWebSocket} (`./ws.ts`) - `graphql-transport-ws` subscriptions over `app.ws()`.
+ * - {@link createPubSub} (`./pubsub.ts`) - an in-memory subscription source; swap for a durable bus.
+ * - {@link mountGraphql} - the one-call sugar that wires POST/GET (and, optionally, subscriptions).
+ *
+ * It executes with `graphql`'s own `parse`/`validate`/`execute`/`subscribe`; no HTTP framework is
+ * re-bundled, the request body reuses core's single bounded trust boundary, and the query text is never
+ * logged. `graphql` is a required peer; `graphql-ws` is optional (needed only for subscriptions).
+ */
+import { respondGraphql } from "./http.js";
+import { graphqlWebSocket } from "./ws.js";
+export { buildContext } from "./context.js";
+export { respondGraphql } from "./http.js";
+export { createPubSub } from "./pubsub.js";
+export { graphqlWebSocket } from "./ws.js";
+/**
+ * Mount a GraphQL endpoint. Wires `POST` (and `GET`, unless disabled) on `path`, injecting the nifra
+ * route context into your resolver context, and - when `subscriptions` is set - a `graphql-ws` WebSocket
+ * on the same path.
+ *
+ * ```ts
+ * import { server } from "@nifrajs/core"
+ * import { websocket } from "@nifrajs/core/ws"
+ * import { mountGraphql, createPubSub } from "@nifrajs/graphql"
+ *
+ * const pubsub = createPubSub()
+ * const app = server().use(websocket())
+ * mountGraphql(app, {
+ *   schema,
+ *   context: ({ nifra }) => ({ user: nifra?.env, pubsub }),
+ *   subscriptions: true,
+ * })
+ * ```
+ */
+export function mountGraphql(app, options) {
+    const path = options.path ?? "/graphql";
+    const enableGet = options.enableGet !== false;
+    const handle = (c) => respondGraphql(c.req, { ...options, nifra: c });
+    app.post(path, handle);
+    if (enableGet)
+        app.get(path, handle);
+    if (options.subscriptions) {
+        if (typeof app.ws !== "function") {
+            throw new Error("mountGraphql: subscriptions require a WebSocket-enabled app - call `.use(websocket())` first.");
+        }
+        let wsOptions;
+        if (options.subscriptions === true) {
+            const ctx = options.context;
+            wsOptions =
+                ctx !== undefined ? { schema: options.schema, context: ctx } : { schema: options.schema };
+        }
+        else {
+            wsOptions = options.subscriptions;
+        }
+        app.ws(path, graphqlWebSocket(wsOptions));
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAA2B,cAAc,EAAE,MAAM,WAAW,CAAA;AACnE,OAAO,EAAyB,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAOjE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAA2B,cAAc,EAAE,MAAM,WAAW,CAAA;AACnE,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAyB,gBAAgB,EAAE,MAAM,SAAS,CAAA;AA0BjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAsB,EACtB,OAA0C;IAE1C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,UAAU,CAAA;IACvC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,KAAK,CAAA;IAE7C,MAAM,MAAM,GAAG,CAAC,CAAwB,EAAqB,EAAE,CAC7D,cAAc,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA;IAEjD,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACtB,IAAI,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAEpC,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QAC1B,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,+FAA+F,CAChG,CAAA;QACH,CAAC;QACD,IAAI,SAAoD,CAAA;QACxD,IAAI,OAAO,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAqE,CAAA;YACzF,SAAS;gBACP,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAA;QAC7F,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,OAAO,CAAC,aAAa,CAAA;QACnC,CAAC;QACD,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAA;IAC3C,CAAC;AACH,CAAC"}

package/dist/pubsub.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A trivial in-memory pub/sub for `subscription` resolvers - the reference implementation of the
+ * subscription source seam. A resolver's `subscribe` returns `pubsub.subscribe(topic)` (an async
+ * iterator); anything in the process calls `pubsub.publish(topic, payload)` to push an event.
+ *
+ * This is deliberately in-process and unbounded-fan-in only within one server instance - the same
+ * single-instance contract as core's `TopicRegistry`. A durable, multi-instance, or tenant-scoped
+ * pub/sub (Redis, a Durable Object, NATS) is an operated concern: implement the same
+ * `{ publish, subscribe }` shape over your bus and pass it in. Keeping only the in-memory impl here is
+ * the guardrail - a durable payload-carrying sink does not belong in a public package.
+ */
+/** The subscription source shape a resolver's `subscribe` consumes. Swap the impl for a durable bus. */
+export interface GraphqlPubSub<Event = unknown> {
+    /** Push `payload` to every open iterator on `topic`. */
+    publish(topic: string, payload: Event): void;
+    /** An async iterator that yields each future `publish(topic, ...)` until it is returned/closed. */
+    subscribe(topic: string): AsyncIterableIterator<Event>;
+}
+/** Create an in-memory {@link GraphqlPubSub}. */
+export declare function createPubSub<Event = unknown>(): GraphqlPubSub<Event>;
+//# sourceMappingURL=pubsub.d.ts.map