@constructive-io/graphql-server 5.20.6 → 5.20.8

package/middleware/graphile.js

@@ -1,15 +1,12 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.graphile = void 0;
 exports.getInFlightCount = getInFlightCount;
 exports.getInFlightKeys = getInFlightKeys;
 exports.clearInFlightMap = clearInFlightMap;
 require("./types"); // for Request type
-const node_crypto_1 = __importDefault(require("node:crypto"));
 const errors_1 = require("@constructive-io/errors");
+const express_context_1 = require("@constructive-io/express-context");
 const env_1 = require("@pgpmjs/env");
 const logger_1 = require("@pgpmjs/logger");
 const graphile_cache_1 = require("graphile-cache");
@@ -21,86 +18,10 @@ const observability_1 = require("../diagnostics/observability");
 const api_errors_1 = require("../errors/api-errors");
 const graphql_response_1 = require("../errors/graphql-response");
 const auth_cookie_plugin_1 = require("../plugins/auth-cookie-plugin");
+const request_protection_plugin_1 = require("../plugins/request-protection-plugin");
+const mask_error_1 = require("./mask-error");
 const graphile_build_stats_1 = require("./observability/graphile-build-stats");
-const maskErrorLog = new logger_1.Logger('graphile:maskError');
 const isDev = () => (0, env_1.getNodeEnv)() === 'development';
-/**
- * GraphQL framework protocol codes. These originate in the GraphQL/grafast
- * transport layer (not in constructive-db), so they are not Constructive domain
- * codes in the `@constructive-io/errors` registry. They are always safe to
- * surface — they carry no sensitive detail. Everything else (auth, account,
- * resource, constraint, and every constructive-db code) is classified by the
- * registry, which is the single source of truth for public vs. internal.
- */
-const GRAPHQL_PROTOCOL_CODES = new Set([
-    'GRAPHQL_VALIDATION_FAILED',
-    'GRAPHQL_PARSE_FAILED',
-    'PERSISTED_QUERY_NOT_FOUND',
-    'PERSISTED_QUERY_NOT_SUPPORTED'
-]);
-/** A code is safe to surface when the registry classifies it public, or it is a
- * GraphQL framework protocol code. */
-const isPublicCode = (code) => Boolean(code) && ((0, errors_1.classify)(code) === 'public' || GRAPHQL_PROTOCOL_CODES.has(code));
-/**
- * Normalize any GraphQL/database error into a canonical Constructive shape.
- *
- * Database errors surface through Grafast without a populated `extensions.code`
- * (the semantic code lives in the message, and any SQLSTATE/DETAIL lives on the
- * underlying pg error at `originalError`). We parse `originalError` first so we
- * can recover the structured code, then fall back to the GraphQL error itself.
- */
-const normalizeError = (error) => {
-    const original = error.originalError;
-    const fromOriginal = original ? (0, errors_1.parse)(original) : null;
-    const parsed = fromOriginal?.code ? fromOriginal : (0, errors_1.parse)(error);
-    return { code: parsed.code, context: parsed.context, class: parsed.class };
-};
-/**
- * Production-aware error handling backed by `@constructive-io/errors`.
- *
- * 1. Enrich `extensions.code`/`class`/`context` from the parsed error so clients
- *    always receive a machine-readable code (fixing the gap where database
- *    errors reached clients as a bare message with empty `extensions`).
- * 2. Surface public (registered/allowlisted) errors as-is.
- * 3. In development, pass everything through (enriched) for debugging.
- * 4. In production, mask internal/unknown errors behind a reference ID and log
- *    the original.
- */
-const maskError = (error) => {
-    const { code, context, class: errorClass } = normalizeError(error);
-    // Lift the structured code onto extensions for every recognized error so
-    // clients always receive a machine-readable code (`extensions` is read-only
-    // on GraphQLError, so we build a formatted error rather than mutating it).
-    const extensions = { ...error.extensions };
-    if (code) {
-        extensions.code = code;
-        extensions.class = errorClass;
-        if (Object.keys(context).length > 0) {
-            extensions.context = context;
-        }
-    }
-    const effectiveCode = code ?? error.extensions?.code;
-    if (isPublicCode(effectiveCode) || (0, env_1.getNodeEnv)() === 'development') {
-        // Note: grafserv strips originalError and internal extensions before
-        // serializing to the client, so returning the enriched error is safe.
-        return {
-            message: error.message,
-            ...(error.locations ? { locations: error.locations } : {}),
-            ...(error.path ? { path: error.path } : {}),
-            extensions,
-        };
-    }
-    // Mask internal/unknown errors with a reference ID.
-    const errorId = node_crypto_1.default.randomBytes(8).toString('hex');
-    maskErrorLog.error(`[masked-error:${errorId}]`, error);
-    return {
-        message: `An unexpected error occurred. Reference: ${errorId}`,
-        extensions: {
-            code: 'INTERNAL_SERVER_ERROR',
-            errorId
-        }
-    };
-};
 // =============================================================================
 // Single-Flight Pattern: In-Flight Tracking
 // =============================================================================
@@ -145,6 +66,7 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
         extends: [(0, graphile_settings_1.createConstructivePreset)(databaseSettings)],
         plugins: [
             auth_cookie_plugin_1.AuthCookiePlugin,
+            request_protection_plugin_1.RequestProtectionPlugin,
             // Only registered when the compute module is provisioned for this
             // database — all schema/table names come from the constructive
             // metaschema (express-context compute module loader); the plugin has
@@ -176,7 +98,7 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
             graphiqlPath: '/graphiql',
             graphiql: true,
             graphiqlOnGraphQLGET: false,
-            maskError
+            maskError: mask_error_1.maskError
         },
         grafast: {
             explain: process.env.NODE_ENV === 'development',
@@ -184,6 +106,11 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                 // In grafserv/express/v4, the request is available at requestContext.expressv4.req
                 const req = requestContext?.expressv4?.req;
                 const context = {};
+                // Timeouts travel with the transaction as GUCs, so they bound the work
+                // this request can do inside PostgreSQL whatever the plan turns out to
+                // be. Resolved per request (not baked into the cached preset) so a
+                // tenant lowering a timeout takes effect on the next request.
+                const timeouts = (0, express_context_1.protectionPgSettings)(req?.requestProtection ?? express_context_1.DEFAULT_REQUEST_PROTECTION);
                 if (req) {
                     if (req.databaseId) {
                         context['jwt.claims.database_id'] = req.databaseId;
@@ -209,6 +136,7 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                     }
                     if (req.token?.user_id) {
                         const pgSettings = {
+                            ...timeouts,
                             role: roleName,
                             'jwt.claims.token_id': req.token.id,
                             'jwt.claims.user_id': req.token.user_id,
@@ -246,15 +174,22 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                     const headerActorId = req.get('X-Actor-Id');
                     if (req.api?.isPublic === false && headerActorId) {
                         const pgSettings = {
+                            ...timeouts,
                             role: roleName,
                             'jwt.claims.user_id': headerActorId,
                             'jwt.claims.principal_id': headerActorId,
                             ...context
                         };
+                        // The entity pair travels together: the tenant's writers reject an
+                        // entity id whose type they cannot interpret (`ENTITY_TYPE_REQUIRED`).
                         const headerEntityId = req.get('X-Entity-Id');
+                        const headerEntityType = req.get('X-Entity-Type');
                         if (headerEntityId) {
                             pgSettings['jwt.claims.entity_id'] = headerEntityId;
                         }
+                        if (headerEntityType) {
+                            pgSettings['jwt.claims.entity_type'] = headerEntityType;
+                        }
                         const headerOrganizationId = req.get('X-Organization-Id');
                         if (headerOrganizationId) {
                             pgSettings['jwt.claims.organization_id'] = headerOrganizationId;
@@ -265,10 +200,20 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                         return { pgSettings };
                     }
                 }
+                // No actor to name, so the tenant database the request addresses carries
+                // the attribution — the same rule the sync gateway applies to a request
+                // that arrives without a credential. Without it the tenant's own writers
+                // refuse the work an anonymous request legitimately does
+                // (`ATTRIBUTION_REQUIRED`), so a public mutation cannot enqueue a job.
                 const anonSettings = {
+                    ...timeouts,
                     role: anonRole,
                     ...context
                 };
+                if (req?.databaseId) {
+                    anonSettings['jwt.claims.entity_id'] = req.databaseId;
+                    anonSettings['jwt.claims.entity_type'] = 'database';
+                }
                 if (req?.requestId) {
                     anonSettings['request.id'] = req.requestId;
                 }

package/middleware/mask-error.d.ts

@@ -0,0 +1,13 @@
+import { type GraphQLError, type GraphQLFormattedError } from 'graphql';
+/**
+ * Production-aware error handling backed by `@constructive-io/errors`.
+ *
+ * 1. Enrich `extensions.code`/`class`/`context` from the parsed error so clients
+ *    always receive a machine-readable code (fixing the gap where database
+ *    errors reached clients as a bare message with empty `extensions`).
+ * 2. Surface public (registered/allowlisted) errors as-is.
+ * 3. In development, pass everything through (enriched) for debugging.
+ * 4. In production, mask internal/unknown errors behind a reference ID and log
+ *    the original.
+ */
+export declare const maskError: (error: GraphQLError) => GraphQLError | GraphQLFormattedError;

package/middleware/mask-error.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskError = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const errors_1 = require("@constructive-io/errors");
+const env_1 = require("@pgpmjs/env");
+const logger_1 = require("@pgpmjs/logger");
+const maskErrorLog = new logger_1.Logger('graphile:maskError');
+/**
+ * GraphQL framework protocol codes. These originate in the GraphQL/grafast
+ * transport layer (not in constructive-db), so they are not Constructive domain
+ * codes in the `@constructive-io/errors` registry. They are always safe to
+ * surface — they carry no sensitive detail. Everything else (auth, account,
+ * resource, constraint, and every constructive-db code) is classified by the
+ * registry, which is the single source of truth for public vs. internal.
+ */
+const GRAPHQL_PROTOCOL_CODES = new Set([
+    'GRAPHQL_VALIDATION_FAILED',
+    'GRAPHQL_PARSE_FAILED',
+    'PERSISTED_QUERY_NOT_FOUND',
+    'PERSISTED_QUERY_NOT_SUPPORTED'
+]);
+/** A code is safe to surface when the registry classifies it public, or it is a
+ * GraphQL framework protocol code. */
+const isPublicCode = (code) => Boolean(code) && ((0, errors_1.classify)(code) === 'public' || GRAPHQL_PROTOCOL_CODES.has(code));
+/**
+ * An error the GraphQL layer raised about the *request*, before any resolver
+ * ran: an unknown input field, a value of the wrong type, a missing required
+ * variable. graphql-js reports variable coercion without an `extensions.code`
+ * (unlike parse/validation, which carry `GRAPHQL_PARSE_FAILED` /
+ * `GRAPHQL_VALIDATION_FAILED`), so code-based classification alone reads it as
+ * unknown and masks it — telling a client its own malformed query was a server
+ * failure, with a reference id pointing at nothing.
+ *
+ * A request error is answered before a field is resolved, so it carries no
+ * response `path` — every execution error has one. Coercion wraps the inner
+ * complaint about the value, so `originalError` may be set, but only ever to
+ * another GraphQL-layer error: anything a resolver or the database threw arrives
+ * as a foreign error (a pg error, an `Error`) and is masked as before. The wrap
+ * is recognized by name rather than by `instanceof`, because the error is raised
+ * by whichever copy of graphql-js grafast resolved, not by this package's.
+ */
+const isGraphQLLayerError = (value) => value == null ||
+    (value.name === 'GraphQLError' &&
+        isGraphQLLayerError(value.originalError));
+const isRequestError = (error) => error.path == null && isGraphQLLayerError(error.originalError);
+/** The code a surfaced request error carries when graphql-js supplied none. */
+const BAD_USER_INPUT = 'BAD_USER_INPUT';
+/**
+ * Normalize any GraphQL/database error into a canonical Constructive shape.
+ *
+ * Database errors surface through Grafast without a populated `extensions.code`
+ * (the semantic code lives in the message, and any SQLSTATE/DETAIL lives on the
+ * underlying pg error at `originalError`). We parse `originalError` first so we
+ * can recover the structured code, then fall back to the GraphQL error itself.
+ */
+const normalizeError = (error) => {
+    const original = error.originalError;
+    const fromOriginal = original ? (0, errors_1.parse)(original) : null;
+    const parsed = fromOriginal?.code ? fromOriginal : (0, errors_1.parse)(error);
+    return { code: parsed.code, context: parsed.context, class: parsed.class };
+};
+/**
+ * Production-aware error handling backed by `@constructive-io/errors`.
+ *
+ * 1. Enrich `extensions.code`/`class`/`context` from the parsed error so clients
+ *    always receive a machine-readable code (fixing the gap where database
+ *    errors reached clients as a bare message with empty `extensions`).
+ * 2. Surface public (registered/allowlisted) errors as-is.
+ * 3. In development, pass everything through (enriched) for debugging.
+ * 4. In production, mask internal/unknown errors behind a reference ID and log
+ *    the original.
+ */
+const maskError = (error) => {
+    const { code, context, class: errorClass } = normalizeError(error);
+    // Lift the structured code onto extensions for every recognized error so
+    // clients always receive a machine-readable code (`extensions` is read-only
+    // on GraphQLError, so we build a formatted error rather than mutating it).
+    const extensions = { ...error.extensions };
+    if (code) {
+        extensions.code = code;
+        extensions.class = errorClass;
+        if (Object.keys(context).length > 0) {
+            extensions.context = context;
+        }
+    }
+    const effectiveCode = code ?? error.extensions?.code;
+    if (!effectiveCode && isRequestError(error)) {
+        extensions.code = BAD_USER_INPUT;
+        return {
+            message: error.message,
+            ...(error.locations ? { locations: error.locations } : {}),
+            extensions,
+        };
+    }
+    if (isPublicCode(effectiveCode) || (0, env_1.getNodeEnv)() === 'development') {
+        // Note: grafserv strips originalError and internal extensions before
+        // serializing to the client, so returning the enriched error is safe.
+        return {
+            message: error.message,
+            ...(error.locations ? { locations: error.locations } : {}),
+            ...(error.path ? { path: error.path } : {}),
+            extensions,
+        };
+    }
+    // Mask internal/unknown errors with a reference ID.
+    const errorId = node_crypto_1.default.randomBytes(8).toString('hex');
+    maskErrorLog.error(`[masked-error:${errorId}]`, error);
+    return {
+        message: `An unexpected error occurred. Reference: ${errorId}`,
+        extensions: {
+            code: 'INTERNAL_SERVER_ERROR',
+            errorId
+        }
+    };
+};
+exports.maskError = maskError;

package/middleware/request-protection.d.ts

@@ -0,0 +1,15 @@
+import './types';
+import type { RequestHandler } from 'express';
+/**
+ * Express middleware that resolves request protection and enforces the one
+ * bound that has to be checked before the body is read.
+ *
+ * The document bounds (depth, cost, page size, introspection) are enforced by
+ * `RequestProtectionPlugin` inside grafast, which is where the parsed document
+ * and coerced variables exist; this middleware exists so the resolved values
+ * are on the request by the time either that plugin or the pgSettings builder
+ * asks for them.
+ *
+ * Mount after the context middleware and before the GraphQL handler.
+ */
+export declare const createRequestProtectionMiddleware: () => RequestHandler;

package/middleware/request-protection.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequestProtectionMiddleware = void 0;
+require("./types"); // for Request type
+const errors_1 = require("@constructive-io/errors");
+const express_context_1 = require("@constructive-io/express-context");
+const graphql_response_1 = require("../errors/graphql-response");
+/**
+ * Resolve the bounds this request runs under and attach them to it.
+ *
+ * The values come from the tenant's own `database_settings`/`api_settings`
+ * (clamped by the platform), read through the cached loader, so the cost is one
+ * routing-plane query per database/API per TTL window. A database with no
+ * settings row — or a request that arrived before the context middleware could
+ * resolve one — still gets the platform defaults, never "unlimited".
+ */
+const resolveProtection = async (req) => {
+    const resolved = await req.constructive?.useModule('requestProtection');
+    return resolved ?? express_context_1.DEFAULT_REQUEST_PROTECTION;
+};
+/**
+ * Multipart requests carry file bodies, which are streamed by the upload
+ * plugin and bounded by the upload limits rather than by the GraphQL request
+ * size: applying a JSON-sized cap to them would reject every upload.
+ */
+const isMultipart = (req) => (req.get('content-type') ?? '').toLowerCase().startsWith('multipart/form-data');
+/**
+ * Express middleware that resolves request protection and enforces the one
+ * bound that has to be checked before the body is read.
+ *
+ * The document bounds (depth, cost, page size, introspection) are enforced by
+ * `RequestProtectionPlugin` inside grafast, which is where the parsed document
+ * and coerced variables exist; this middleware exists so the resolved values
+ * are on the request by the time either that plugin or the pgSettings builder
+ * asks for them.
+ *
+ * Mount after the context middleware and before the GraphQL handler.
+ */
+const createRequestProtectionMiddleware = () => {
+    return async (req, res, next) => {
+        // A lookup failure is neither "unlimited" nor "the defaults": the request
+        // has no known bounds, so it is handed to the error handler rather than
+        // served under numbers nobody chose.
+        let protection;
+        try {
+            protection = await resolveProtection(req);
+        }
+        catch (e) {
+            next(e);
+            return;
+        }
+        req.requestProtection = protection;
+        const declaredLength = Number(req.get('content-length') ?? '');
+        if (Number.isFinite(declaredLength) &&
+            declaredLength > protection.maxRequestBytes &&
+            !isMultipart(req)) {
+            (0, graphql_response_1.respondWithGraphQLError)(res, errors_1.errors.REQUEST_TOO_LARGE({ bytes: declaredLength, limit: protection.maxRequestBytes }));
+            return;
+        }
+        next();
+    };
+};
+exports.createRequestProtectionMiddleware = createRequestProtectionMiddleware;

package/middleware/types.d.ts

@@ -1,3 +1,4 @@
+import type { RequestProtection } from '@constructive-io/express-context';
 import type { ApiStructure } from '../types';
 export type ConstructiveAPIToken = {
     id?: string;
@@ -19,6 +20,12 @@ declare global {
             token?: ConstructiveAPIToken;
             /** Device token from constructive_device_token cookie for trusted device tracking */
             deviceToken?: string;
+            /**
+             * Per-request protection bounds, resolved from the tenant's
+             * database/API settings and clamped by the platform. Set by
+             * `createRequestProtectionMiddleware`.
+             */
+            requestProtection?: RequestProtection;
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.20.6",
+  "version": "5.20.8",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -42,40 +42,40 @@
   ],
   "dependencies": {
     "@agentic-kit/ollama": "2.14.0",
-    "@constructive-io/csrf": "^0.29.0",
-    "@constructive-io/errors": "^0.11.1",
-    "@constructive-io/express-context": "^0.26.1",
-    "@constructive-io/graphql-env": "^3.31.1",
-    "@constructive-io/graphql-types": "^3.30.1",
-    "@constructive-io/llm-env": "^0.14.0",
-    "@constructive-io/query-builder": "^3.13.2",
-    "@constructive-io/s3-utils": "^2.32.0",
-    "@constructive-io/url-domains": "^2.30.0",
+    "@constructive-io/csrf": "^0.29.1",
+    "@constructive-io/errors": "^0.11.2",
+    "@constructive-io/express-context": "^0.26.2",
+    "@constructive-io/graphql-env": "^3.31.2",
+    "@constructive-io/graphql-types": "^3.30.2",
+    "@constructive-io/llm-env": "^0.14.1",
+    "@constructive-io/query-builder": "^3.13.3",
+    "@constructive-io/s3-utils": "^2.33.0",
+    "@constructive-io/url-domains": "^2.30.1",
     "@graphile-contrib/pg-many-to-many": "2.0.0-rc.2",
-    "@pgpmjs/env": "^2.43.1",
-    "@pgpmjs/logger": "^2.25.0",
-    "@pgpmjs/server-utils": "^3.27.1",
-    "@pgpmjs/types": "^2.52.1",
+    "@pgpmjs/env": "^2.43.2",
+    "@pgpmjs/logger": "^2.25.1",
+    "@pgpmjs/server-utils": "^3.27.2",
+    "@pgpmjs/types": "^2.53.0",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",
     "express": "^5.2.1",
-    "gql-ast": "^3.24.0",
+    "gql-ast": "^3.24.1",
     "grafast": "1.1.2",
     "grafserv": "1.0.1",
     "graphile-build": "5.1.1",
     "graphile-build-pg": "5.1.3",
-    "graphile-cache": "^4.12.1",
+    "graphile-cache": "^4.12.2",
     "graphile-config": "1.1.0",
-    "graphile-function-bindings": "^1.14.2",
-    "graphile-settings": "^6.21.2",
+    "graphile-function-bindings": "^1.14.3",
+    "graphile-settings": "^6.21.3",
     "graphile-utils": "5.0.3",
     "graphql": "16.13.0",
     "graphql-upload": "^13.0.0",
     "lru-cache": "^11.2.7",
     "pg": "^8.21.0",
-    "pg-cache": "^3.27.1",
-    "pg-env": "^1.31.0",
-    "pg-query-context": "^2.30.0",
+    "pg-cache": "^3.27.2",
+    "pg-env": "^1.31.1",
+    "pg-query-context": "^2.30.1",
     "pg-sql2": "5.0.1",
     "postgraphile": "5.1.4",
     "request-ip": "^3.3.0"
@@ -90,11 +90,11 @@
     "@types/request-ip": "^0.0.41",
     "@types/supertest": "^7.2.1",
     "cookie-parser": "^1.4.7",
-    "graphile-test": "5.14.2",
-    "makage": "^0.3.0",
+    "graphile-test": "5.14.3",
+    "makage": "^0.8.0",
     "nodemon": "^3.1.14",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "608acc891de5197ad3cb4bfd0babe1050dbec24a"
+  "gitHead": "4deb5b9a00ead37453857d24274007255092822e"
 }

package/plugins/request-protection-plugin.d.ts

@@ -0,0 +1,15 @@
+import '../middleware/types';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * RequestProtectionPlugin — applies a tenant's document bounds to every
+ * operation.
+ *
+ * The check runs in `prepareArgs` rather than `parseAndValidate` for one
+ * reason: `parseAndValidate` sees no request, so it could only enforce the
+ * bounds baked into the schema's preset at build time — and a Graphile
+ * instance is cached per API for as long as the schema is valid, so a tenant
+ * lowering a limit would not take effect until the cache turned over.
+ * `prepareArgs` carries both the request (hence the freshly resolved settings)
+ * and the coerced variables, which is also what makes `first: $n` enforceable.
+ */
+export declare const RequestProtectionPlugin: GraphileConfig.Plugin;

package/plugins/request-protection-plugin.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestProtectionPlugin = void 0;
+require("../middleware/types"); // for Request type
+const express_context_1 = require("@constructive-io/express-context");
+const document_gate_1 = require("../protection/document-gate");
+/**
+ * Get the Express request from a grafserv request context.
+ */
+const getExpressRequest = (requestContext) => requestContext?.expressv4?.req;
+/**
+ * RequestProtectionPlugin — applies a tenant's document bounds to every
+ * operation.
+ *
+ * The check runs in `prepareArgs` rather than `parseAndValidate` for one
+ * reason: `parseAndValidate` sees no request, so it could only enforce the
+ * bounds baked into the schema's preset at build time — and a Graphile
+ * instance is cached per API for as long as the schema is valid, so a tenant
+ * lowering a limit would not take effect until the cache turned over.
+ * `prepareArgs` carries both the request (hence the freshly resolved settings)
+ * and the coerced variables, which is also what makes `first: $n` enforceable.
+ */
+exports.RequestProtectionPlugin = {
+    name: 'RequestProtectionPlugin',
+    version: '0.0.0',
+    description: 'Enforces per-request query depth, cost, page size and introspection bounds resolved from database_settings/api_settings.',
+    grafast: {
+        middleware: {
+            prepareArgs(next, event) {
+                const { args } = event;
+                const req = getExpressRequest(args.requestContext);
+                // No resolved settings means the protection middleware did not run for
+                // this request (an embedded/test harness mounting grafserv directly);
+                // the platform defaults still apply rather than nothing at all.
+                const protection = req?.requestProtection ?? express_context_1.DEFAULT_REQUEST_PROTECTION;
+                if (args.document && args.schema) {
+                    (0, document_gate_1.enforceDocumentProtection)(args.schema, args.document, args.variableValues, protection, args.operationName);
+                }
+                return next();
+            }
+        }
+    }
+};

package/protection/document-gate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Document gate — depth, cost, page size and introspection limits.
+ *
+ * A statement timeout stops a slow query; it does not stop a cheap-looking one
+ * that asks for a million rows across nested connections, because that request
+ * spends its budget in output size and memory rather than in a single statement.
+ * These bounds are therefore checked against the *document*, before any plan is
+ * executed.
+ *
+ * Cost is measured as the number of rows the operation can pull: a connection
+ * contributes its page size multiplied by the page sizes of every connection
+ * above it, so `users(first: 100) { posts(first: 100) }` costs 100 + 10,000
+ * rather than the 4 fields it looks like. A connection with no `first`/`last`
+ * is charged `ASSUMED_PAGE_SIZE`, since it is unbounded in principle.
+ *
+ * The walk is manual rather than `visitWithTypeInfo` because fragment spreads
+ * have to be followed (a document can hide its depth entirely inside
+ * fragments) and the visitor does not follow them.
+ */
+import { type RequestProtection } from '@constructive-io/express-context';
+import type { DocumentNode, GraphQLSchema } from 'graphql';
+export interface DocumentAnalysis {
+    /** Deepest field nesting in the operation. */
+    depth: number;
+    /** Rows the operation can pull across all of its connections. */
+    cost: number;
+}
+/**
+ * Enforce the document-level bounds for one operation.
+ *
+ * Throws the matching public error on the first bound exceeded; returns what it
+ * measured otherwise, so a caller can log or expose it.
+ */
+export declare function enforceDocumentProtection(schema: GraphQLSchema, document: DocumentNode, variableValues: Record<string, unknown> | null | undefined, protection: RequestProtection, operationName?: string | null): DocumentAnalysis;