@constructive-io/graphql-server 5.20.8 → 5.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.20.8",
+  "version": "5.22.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -43,19 +43,19 @@
   "dependencies": {
     "@agentic-kit/ollama": "2.14.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/errors": "^0.13.0",
+    "@constructive-io/express-context": "^0.28.0",
+    "@constructive-io/graphql-env": "^3.32.0",
+    "@constructive-io/graphql-types": "^3.31.0",
     "@constructive-io/llm-env": "^0.14.1",
-    "@constructive-io/query-builder": "^3.13.3",
+    "@constructive-io/query-builder": "^3.13.5",
     "@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.2",
+    "@pgpmjs/env": "^2.43.4",
     "@pgpmjs/logger": "^2.25.1",
-    "@pgpmjs/server-utils": "^3.27.2",
-    "@pgpmjs/types": "^2.53.0",
+    "@pgpmjs/server-utils": "^3.27.4",
+    "@pgpmjs/types": "^2.53.2",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",
     "express": "^5.2.1",
@@ -64,16 +64,16 @@
     "grafserv": "1.0.1",
     "graphile-build": "5.1.1",
     "graphile-build-pg": "5.1.3",
-    "graphile-cache": "^4.12.2",
+    "graphile-cache": "^4.12.4",
     "graphile-config": "1.1.0",
-    "graphile-function-bindings": "^1.14.3",
-    "graphile-settings": "^6.21.3",
+    "graphile-function-bindings": "^1.14.5",
+    "graphile-settings": "^6.21.5",
     "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.2",
+    "pg-cache": "^3.27.4",
     "pg-env": "^1.31.1",
     "pg-query-context": "^2.30.1",
     "pg-sql2": "5.0.1",
@@ -90,11 +90,11 @@
     "@types/request-ip": "^0.0.41",
     "@types/supertest": "^7.2.1",
     "cookie-parser": "^1.4.7",
-    "graphile-test": "5.14.3",
+    "graphile-test": "5.14.5",
     "makage": "^0.8.0",
     "nodemon": "^3.1.14",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "4deb5b9a00ead37453857d24274007255092822e"
+  "gitHead": "01e073830677c0587bab564b7d575a06b5156f0c"
 }

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

@@ -1,5 +1,8 @@
 import '../middleware/types';
+import type { RefusalReason } from '@constructive-io/express-context';
 import type { GraphileConfig } from 'graphile-config';
+/** The refusal a gate rejection counts as, or undefined for any other error. */
+export declare const documentRefusalReason: (err: unknown) => RefusalReason | undefined;
 /**
  * RequestProtectionPlugin — applies a tenant's document bounds to every
  * operation.

package/plugins/request-protection-plugin.js

@@ -1,9 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RequestProtectionPlugin = void 0;
+exports.RequestProtectionPlugin = exports.documentRefusalReason = void 0;
 require("../middleware/types"); // for Request type
 const express_context_1 = require("@constructive-io/express-context");
+const grafast_1 = require("grafast");
 const document_gate_1 = require("../protection/document-gate");
+const recorder_1 = require("../refusals/recorder");
+/** The document-gate error codes, as the refusal taxonomy names them. */
+const DOCUMENT_REFUSALS = {
+    QUERY_TOO_DEEP: 'query_too_deep',
+    QUERY_TOO_COSTLY: 'query_too_costly',
+    PAGE_SIZE_TOO_LARGE: 'page_size_too_large'
+};
+/** The refusal a gate rejection counts as, or undefined for any other error. */
+const documentRefusalReason = (err) => {
+    if (!(err instanceof grafast_1.SafeError))
+        return undefined;
+    const code = err.extensions?.code;
+    return typeof code === 'string' ? DOCUMENT_REFUSALS[code] : undefined;
+};
+exports.documentRefusalReason = documentRefusalReason;
 /**
  * Get the Express request from a grafserv request context.
  */
@@ -34,7 +50,17 @@ exports.RequestProtectionPlugin = {
                 // 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);
+                    try {
+                        (0, document_gate_1.enforceDocumentProtection)(args.schema, args.document, args.variableValues, protection, args.operationName);
+                    }
+                    catch (err) {
+                        // The rejection is still the client's `SafeError`; it is counted on
+                        // the way out, keyed by the tenant the request resolved.
+                        const reason = (0, exports.documentRefusalReason)(err);
+                        if (reason && req)
+                            (0, recorder_1.recordRefusal)(req, reason);
+                        throw err;
+                    }
                 }
                 return next();
             }

package/refusals/recorder.d.ts

@@ -0,0 +1,78 @@
+import '../middleware/types';
+import type { RefusalReason, RefusalRecorderStats } from '@constructive-io/express-context';
+import { RefusalRecorder } from '@constructive-io/express-context';
+import type { ConstructiveOptions } from '@constructive-io/graphql-types';
+import type { Request } from 'express';
+import type { Pool } from 'pg';
+/**
+ * refusals/recorder — the GraphQL lane's `RefusalRecorder`.
+ *
+ * One recorder per process, installed by the server at startup and read by
+ * every refusal site through `recordRefusal`. Emitters never see the recorder,
+ * the pool or a promise: `recordRefusal` is a synchronous counter bump that
+ * cannot fail the response being written around it. A harness that mounts a
+ * middleware without a server has no recorder installed and the call is a
+ * no-op.
+ *
+ * ## Flush identity
+ *
+ * A flush runs outside any tenant request, so it establishes its own identity
+ * at the top of its transaction: the `platform-bootstrap` service principal
+ * (`jwt.claims.user_id` / `principal_id`) attributed to the platform database
+ * (`jwt.claims.database_id`, `entity_id`, `entity_type`) as the platform
+ * `system` role type (`jwt.claims.role_type`), which the generated writer's
+ * guard and RESTRICTIVE insert policy require. Those are the claims every
+ * other unattended platform write carries; resolving them is the
+ * claim-establishment step at the entry point, not a lookup inside the
+ * function being called — `record_refusals` raises if the claims are missing.
+ * Resolution is cached after the first success; a failure is reported by the
+ * recorder as a failed flush (loud, every interval) and retried next time.
+ *
+ * @module refusals/recorder
+ */
+/** The principal an unattended platform write acts as. */
+export declare const PLATFORM_BOOTSTRAP_PRINCIPAL = "platform-bootstrap";
+/** Make `recorder` the process's recorder. Returns the previous one, if any. */
+export declare const installRefusalRecorder: (recorder: RefusalRecorder | null) => RefusalRecorder | null;
+export declare const getRefusalRecorder: () => RefusalRecorder | null;
+export declare const getRefusalRecorderStats: () => RefusalRecorderStats | null;
+/** The route half of a refusal key — the same shape admission control keys on. */
+export declare const routeKeyOf: (req: Request) => string;
+export interface RecordRefusalOptions {
+    /** Overrides the address the refusal is attributed to. */
+    sourceIp?: string | null;
+    /** See `AdmissionControlOptions.trustedProxyHops`. */
+    trustedProxyHops?: number;
+    /** Overrides `req.databaseId`. */
+    databaseId?: string | null;
+}
+/**
+ * Count one GraphQL-lane refusal. Synchronous; never throws; does nothing
+ * when no recorder is installed.
+ */
+export declare const recordRefusal: (req: Request, reason: RefusalReason, opts?: RecordRefusalOptions) => void;
+interface PlatformFlushIdentity {
+    databaseId: string;
+    actorId: string;
+    principalId: string;
+}
+/**
+ * Resolve the claims a flush runs under: the platform database and the
+ * `platform-bootstrap` service principal's user row. Throws — with the row
+ * that was missing named — rather than returning a partial identity.
+ */
+export declare const resolvePlatformFlushIdentity: (pool: Pool, principalName?: string) => Promise<PlatformFlushIdentity>;
+export declare const platformFlushClaims: (identity: PlatformFlushIdentity) => Record<string, string>;
+export interface PlatformRefusalRecorderOptions {
+    intervalMs?: number;
+    jitterMs?: number;
+    maxKeys?: number;
+    principalName?: string;
+}
+/**
+ * The recorder the server runs: counts in memory, flushes into
+ * `constructive_usage_private.record_refusals` on the platform pool under the
+ * platform flush identity. Not started; the caller owns start/stop.
+ */
+export declare const createPlatformRefusalRecorder: (opts: ConstructiveOptions, recorderOpts?: PlatformRefusalRecorderOptions) => RefusalRecorder;
+export {};

package/refusals/recorder.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPlatformRefusalRecorder = exports.platformFlushClaims = exports.resolvePlatformFlushIdentity = exports.recordRefusal = exports.routeKeyOf = exports.getRefusalRecorderStats = exports.getRefusalRecorder = exports.installRefusalRecorder = exports.PLATFORM_BOOTSTRAP_PRINCIPAL = void 0;
+require("../middleware/types"); // for Request type
+const express_context_1 = require("@constructive-io/express-context");
+const logger_1 = require("@pgpmjs/logger");
+const pg_cache_1 = require("pg-cache");
+const log = new logger_1.Logger('refusals');
+/**
+ * refusals/recorder — the GraphQL lane's `RefusalRecorder`.
+ *
+ * One recorder per process, installed by the server at startup and read by
+ * every refusal site through `recordRefusal`. Emitters never see the recorder,
+ * the pool or a promise: `recordRefusal` is a synchronous counter bump that
+ * cannot fail the response being written around it. A harness that mounts a
+ * middleware without a server has no recorder installed and the call is a
+ * no-op.
+ *
+ * ## Flush identity
+ *
+ * A flush runs outside any tenant request, so it establishes its own identity
+ * at the top of its transaction: the `platform-bootstrap` service principal
+ * (`jwt.claims.user_id` / `principal_id`) attributed to the platform database
+ * (`jwt.claims.database_id`, `entity_id`, `entity_type`) as the platform
+ * `system` role type (`jwt.claims.role_type`), which the generated writer's
+ * guard and RESTRICTIVE insert policy require. Those are the claims every
+ * other unattended platform write carries; resolving them is the
+ * claim-establishment step at the entry point, not a lookup inside the
+ * function being called — `record_refusals` raises if the claims are missing.
+ * Resolution is cached after the first success; a failure is reported by the
+ * recorder as a failed flush (loud, every interval) and retried next time.
+ *
+ * @module refusals/recorder
+ */
+/** The principal an unattended platform write acts as. */
+exports.PLATFORM_BOOTSTRAP_PRINCIPAL = 'platform-bootstrap';
+let installed = null;
+/** Make `recorder` the process's recorder. Returns the previous one, if any. */
+const installRefusalRecorder = (recorder) => {
+    const previous = installed;
+    installed = recorder;
+    return previous;
+};
+exports.installRefusalRecorder = installRefusalRecorder;
+const getRefusalRecorder = () => installed;
+exports.getRefusalRecorder = getRefusalRecorder;
+const getRefusalRecorderStats = () => installed?.stats() ?? null;
+exports.getRefusalRecorderStats = getRefusalRecorderStats;
+/** The route half of a refusal key — the same shape admission control keys on. */
+const routeKeyOf = (req) => `${req.method} ${req.baseUrl ?? ''}${req.path ?? req.url ?? ''}`;
+exports.routeKeyOf = routeKeyOf;
+/**
+ * How far back through `X-Forwarded-For` to believe; mirrors admission
+ * control's resolution so the refusal source is the same address the limiter
+ * keyed on.
+ */
+const resolveHops = (req, configured) => {
+    if (typeof configured === 'number')
+        return configured;
+    const fromEnv = (0, express_context_1.trustedProxyHops)();
+    if (fromEnv > 0)
+        return fromEnv;
+    return req.app?.get('trust proxy') ? 1 : 0;
+};
+/**
+ * Count one GraphQL-lane refusal. Synchronous; never throws; does nothing
+ * when no recorder is installed.
+ */
+const recordRefusal = (req, reason, opts = {}) => {
+    const recorder = installed;
+    if (!recorder)
+        return;
+    const refusal = {
+        databaseId: opts.databaseId !== undefined ? opts.databaseId : req.databaseId ?? null,
+        lane: 'graphql',
+        reason,
+        routeKey: (0, exports.routeKeyOf)(req),
+        sourceIp: opts.sourceIp !== undefined
+            ? opts.sourceIp
+            : (0, express_context_1.clientIpFrom)(req, resolveHops(req, opts.trustedProxyHops))
+    };
+    try {
+        recorder.record(refusal);
+    }
+    catch (err) {
+        // The refusal response is already being written; a broken recorder is
+        // reported here and via the recorder's own stats, never to the client.
+        log.error(`refusal not recorded reason=${reason}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+};
+exports.recordRefusal = recordRefusal;
+/**
+ * Resolve the claims a flush runs under: the platform database and the
+ * `platform-bootstrap` service principal's user row. Throws — with the row
+ * that was missing named — rather than returning a partial identity.
+ */
+const resolvePlatformFlushIdentity = async (pool, principalName = exports.PLATFORM_BOOTSTRAP_PRINCIPAL) => {
+    const database = await pool.query(`SELECT id FROM metaschema_public.database WHERE platform IS TRUE`);
+    if (database.rowCount !== 1) {
+        throw new Error(`refusals: expected exactly one platform database (metaschema_public.database.platform), found ${database.rowCount}`);
+    }
+    const principal = await pool.query(`SELECT user_id, bypass_step_up FROM constructive_auth_public.principals WHERE name = $1`, [principalName]);
+    if (principal.rowCount !== 1) {
+        throw new Error(`refusals: no service principal named '${principalName}'`);
+    }
+    if (principal.rows[0].bypass_step_up !== true) {
+        throw new Error(`refusals: principal '${principalName}' is not a service principal (no bypass_step_up)`);
+    }
+    return {
+        databaseId: database.rows[0].id,
+        actorId: principal.rows[0].user_id,
+        principalId: principal.rows[0].user_id
+    };
+};
+exports.resolvePlatformFlushIdentity = resolvePlatformFlushIdentity;
+const platformFlushClaims = (identity) => ({
+    'jwt.claims.database_id': identity.databaseId,
+    'jwt.claims.user_id': identity.actorId,
+    'jwt.claims.principal_id': identity.principalId,
+    'jwt.claims.entity_id': identity.databaseId,
+    'jwt.claims.entity_type': 'database',
+    'jwt.claims.role_type': 'system'
+});
+exports.platformFlushClaims = platformFlushClaims;
+/**
+ * The recorder the server runs: counts in memory, flushes into
+ * `constructive_usage_private.record_refusals` on the platform pool under the
+ * platform flush identity. Not started; the caller owns start/stop.
+ */
+const createPlatformRefusalRecorder = (opts, recorderOpts = {}) => {
+    const pool = (0, pg_cache_1.getPgPool)(opts.pg);
+    let cached = null;
+    const claims = async () => {
+        if (cached)
+            return cached;
+        cached = (0, exports.platformFlushClaims)(await (0, exports.resolvePlatformFlushIdentity)(pool, recorderOpts.principalName));
+        log.info(`[refusals] flushing as '${recorderOpts.principalName ?? exports.PLATFORM_BOOTSTRAP_PRINCIPAL}'`);
+        return cached;
+    };
+    return new express_context_1.RefusalRecorder({
+        sink: (0, express_context_1.createRecordRefusalsSink)({ pool, claims }),
+        intervalMs: recorderOpts.intervalMs,
+        jitterMs: recorderOpts.jitterMs,
+        maxKeys: recorderOpts.maxKeys
+    });
+};
+exports.createPlatformRefusalRecorder = createPlatformRefusalRecorder;

package/server.d.ts

@@ -33,6 +33,7 @@ declare class Server {
     private closed;
     private httpServer;
     private debugSampler;
+    private refusalRecorder;
     constructor(opts: ConstructiveOptions);
     listen(): HttpServer;
     flush(databaseId: string): Promise<void>;

package/server.js

@@ -20,6 +20,7 @@ const agentic_1 = require("./agentic");
 const debug_db_snapshot_1 = require("./diagnostics/debug-db-snapshot");
 const debug_sampler_1 = require("./diagnostics/debug-sampler");
 const observability_1 = require("./diagnostics/observability");
+const admission_control_1 = require("./middleware/admission-control");
 const api_1 = require("./middleware/api");
 const auth_1 = require("./middleware/auth");
 // Auth cookie handling is done via AuthCookiePlugin in grafserv
@@ -38,6 +39,7 @@ const guard_1 = require("./middleware/observability/guard");
 const request_logger_1 = require("./middleware/observability/request-logger");
 const request_protection_1 = require("./middleware/request-protection");
 const routing_1 = require("./middleware/routing");
+const recorder_1 = require("./refusals/recorder");
 const log = new logger_1.Logger('server');
 /**
  * Creates and starts a GraphQL server instance
@@ -76,6 +78,7 @@ class Server {
     closed = false;
     httpServer = null;
     debugSampler = null;
+    refusalRecorder = null;
     constructor(opts) {
         this.opts = (0, graphql_env_1.getEnvOptions)(opts);
         const effectiveOpts = this.opts;
@@ -153,6 +156,13 @@ class Server {
         // Resolve the tenant's protection bounds before anything can spend budget
         // on the request (and before the GraphQL handler reads them for pgSettings).
         app.use((0, request_protection_1.createRequestProtectionMiddleware)());
+        // Spend the width and rate bounds the line above resolved, before a
+        // request can take a pool connection. Scoped to /graphql rather than
+        // mounted globally because a concurrency slot is held for as long as the
+        // handler runs: the SSE routes below are long-lived by design and would
+        // sit in the budget for the life of the stream. The other lanes need
+        // their own bound sized for streaming, not this one.
+        app.use('/graphql', (0, admission_control_1.createAdmissionControlMiddleware)());
         app.use((0, captcha_1.createCaptchaMiddleware)());
         // CSRF protection for cookie-authenticated requests
         // Skip CSRF for Bearer token auth (not vulnerable to CSRF) and anonymous requests
@@ -188,12 +198,17 @@ class Server {
         // REST function invocation routes (POST /fn/:alias, GET /fn/invocations/:id)
         app.use((0, fn_1.createFnRouter)());
         app.use((0, graphile_1.graphile)(effectiveOpts));
-        app.use(flush_1.flush);
+        app.use((0, flush_1.createFlushMiddleware)(effectiveOpts));
         // Error handling - MUST be LAST
         app.use(error_handler_1.notFoundHandler); // Catches unmatched routes (404)
         app.use(error_handler_1.errorHandler); // Catches all thrown errors
         this.app = app;
         this.debugSampler = observabilityEnabled ? (0, debug_sampler_1.startDebugSampler)(effectiveOpts) : null;
+        // Refusals are counted in memory by the middleware above and flushed to
+        // the platform table on a timer; the request path never touches the pool.
+        this.refusalRecorder = (0, recorder_1.createPlatformRefusalRecorder)(effectiveOpts);
+        (0, recorder_1.installRefusalRecorder)(this.refusalRecorder);
+        this.refusalRecorder.start();
     }
     listen() {
         const { server } = this.opts;
@@ -298,6 +313,11 @@ class Server {
         this.closed = true;
         this.shuttingDown = true;
         await this.removeEventListener();
+        if (this.refusalRecorder) {
+            (0, recorder_1.installRefusalRecorder)(null);
+            await this.refusalRecorder.stop();
+            this.refusalRecorder = null;
+        }
         if (this.debugSampler) {
             await this.debugSampler.stop();
             this.debugSampler = null;