@constructive-io/graphql-server 5.21.0 → 5.23.0

package/README.md

@@ -95,7 +95,7 @@ For the operational workflow, sampler output, and heap snapshot usage, see [docs
 - `GET /graphiql` -> GraphiQL UI
 - `GET /graphql` / `POST /graphql` -> GraphQL endpoint
 - `POST /graphql` (multipart) -> file uploads
-- `POST /flush` -> clears cached Graphile schema for the current API
+- `POST /flush` -> clears cached Graphile schema for the current API; mounted only when `API_FLUSH_TOKEN` is set, and requires `Authorization: Bearer $API_FLUSH_TOKEN`. Without the variable the route is not served (404) — operators deploying a schema-cache flush must set it on the server and on every caller. The `LISTEN/NOTIFY` invalidation path is unaffected.
 - `GET /debug/memory` -> memory/process/Graphile debug snapshot when observability is enabled
 - `GET /debug/db` -> PostgreSQL activity/locks/pool debug snapshot when observability is enabled
 
@@ -132,6 +132,8 @@ Configuration is merged from defaults, config files, and env vars via `@construc
 | `API_META_SCHEMAS`             | Meta schemas to query                 | `routing_public,metaschema_public,metaschema_modules_public` |
 | `API_ANON_ROLE`                | Anonymous role name                   | `administrator`                                               |
 | `API_ROLE_NAME`                | Authenticated role name               | `administrator`                                               |
+| `API_FLUSH_TOKEN`              | Bearer token required by `POST /flush`; route is not mounted when unset | empty                        |
+| `API_INTROSPECTION_ROLE`       | Role PostGraphile introspects as; unset means the pool's connecting role. Naming a role with fewer grants removes fields from the schema | empty |
 | `GRAPHQL_OBSERVABILITY_ENABLED` | Master switch for debug routes and sampler | `false`                                                  |
 | `GRAPHQL_DEBUG_SAMPLER_ENABLED` | Enables periodic NDJSON sampling when observability is on | `true`                                   |
 | `GRAPHQL_DEBUG_SAMPLER_INTERVAL_MS` | Sampler interval in milliseconds | `10000`                                                       |

package/esm/index.js

@@ -3,5 +3,5 @@ export * from './server';
 export { createApiMiddleware, getApiConfig, getSubdomain } from './middleware/api';
 export { createAuthenticateMiddleware } from './middleware/auth';
 export { cors } from './middleware/cors';
-export { flush, flushService } from './middleware/flush';
+export { createFlushMiddleware, flushService } from './middleware/flush';
 export { graphile } from './middleware/graphile';

package/esm/middleware/flush.js

@@ -1,19 +1,50 @@
 import './types'; // for Request type
 import { Logger } from '@pgpmjs/logger';
 import { svcCache } from '@pgpmjs/server-utils';
+import { createHash, timingSafeEqual } from 'crypto';
 import { graphileCache } from 'graphile-cache';
 import { getPgPool } from 'pg-cache';
 import { getRoutingSchema, isValidSchemaName } from './routing';
 const log = new Logger('flush');
-export const flush = async (req, res, next) => {
-    if (req.url === '/flush') {
-        // TODO: check bearer for a flush / special key
+const bearerToken = (req) => {
+    const header = req.get('authorization');
+    if (!header)
+        return null;
+    const [scheme, ...rest] = header.trim().split(/\s+/);
+    if (scheme.toLowerCase() !== 'bearer' || rest.length !== 1)
+        return null;
+    return rest[0];
+};
+// Compare digests rather than the tokens themselves: timingSafeEqual requires
+// equal lengths, and digests are equal-length whatever the caller presents.
+const tokensMatch = (presented, expected) => timingSafeEqual(createHash('sha256').update(presented).digest(), createHash('sha256').update(expected).digest());
+/**
+ * `/flush` drops the routing and schema caches for the request's service key,
+ * so it is a control-plane operation: it needs the flush secret, not a tenant
+ * session. Without a configured secret there is no way to authenticate the
+ * caller, so the route stays closed.
+ */
+export const createFlushMiddleware = (opts) => {
+    const expected = opts.api?.flushToken;
+    return async (req, res, next) => {
+        if (req.url !== '/flush') {
+            return next();
+        }
+        if (!expected) {
+            log.warn('[flush] rejected: no api.flushToken configured');
+            res.status(404).send('Not Found');
+            return;
+        }
+        const presented = bearerToken(req);
+        if (!presented || !tokensMatch(presented, expected)) {
+            log.warn('[flush] rejected: invalid or missing bearer token');
+            res.status(401).send('Unauthorized');
+            return;
+        }
         graphileCache.delete(req.svc_key);
         svcCache.delete(req.svc_key);
         res.status(200).send('OK');
-        return;
-    }
-    return next();
+    };
 };
 export const flushService = async (opts, databaseId) => {
     const pgPool = getPgPool(opts.pg);

package/esm/middleware/graphile.js

@@ -12,6 +12,7 @@ import { isGraphqlObservabilityEnabled } from '../diagnostics/observability';
 import { HandlerCreationError } from '../errors/api-errors';
 import { respondWithGraphQLError } from '../errors/graphql-response';
 import { AuthCookiePlugin } from '../plugins/auth-cookie-plugin';
+import { createErrorEventsPlugin } from '../plugins/error-events-plugin';
 import { RequestProtectionPlugin } from '../plugins/request-protection-plugin';
 import { maskError } from './mask-error';
 import { observeGraphileBuild } from './observability/graphile-build-stats';
@@ -55,12 +56,13 @@ const reqLabel = (req) => (req.requestId ? `[${req.requestId}]` : '[req]');
  * plugin preset.  Without settings the default preset is used
  * (everything on except aggregates).
  */
-const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId, compute) => {
+const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, databaseSettings, apiId, compute) => {
     return {
         extends: [createConstructivePreset(databaseSettings)],
         plugins: [
             AuthCookiePlugin,
             RequestProtectionPlugin,
+            createErrorEventsPlugin(pool),
             // 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
@@ -84,7 +86,15 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
         pgServices: [
             makePgService({
                 pool,
-                schemas
+                schemas,
+                // Introspection runs outside any request, so it has no served role to
+                // inherit: unset, it reads the catalog as whatever role the pool
+                // connected as (a superuser in most deployments) and the schema
+                // advertises that role's reach. Naming the role keeps schema shape
+                // tied to a bounded role's grants.
+                ...(introspectionRole && {
+                    pgSettingsForIntrospection: { role: introspectionRole }
+                })
             })
         ],
         grafserv: {
@@ -139,6 +149,15 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                         if (req.token.session_id) {
                             pgSettings['jwt.claims.session_id'] = req.token.session_id;
                         }
+                        if (req.token.root_session_id) {
+                            pgSettings['jwt.claims.root_session_id'] = req.token.root_session_id;
+                        }
+                        if (req.token.parent_session_id) {
+                            pgSettings['jwt.claims.parent_session_id'] = req.token.parent_session_id;
+                        }
+                        if (req.token.intent) {
+                            pgSettings['jwt.claims.intent'] = req.token.intent;
+                        }
                         // Propagate credential metadata as JWT claims so PG functions
                         // can read them via current_setting('jwt.claims.access_level') etc.
                         if (req.token.access_level) {
@@ -287,7 +306,7 @@ export const graphile = (opts) => {
             const pool = getPgPool(pgConfig);
             // Create promise and store in in-flight map BEFORE try block
             const compute = api.apiId ? await req.constructive?.useModule('compute') : undefined;
-            const preset = buildPreset(pool, schema || [], anonRole, roleName, api.databaseSettings, api.apiId, compute);
+            const preset = buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, api.databaseSettings, api.apiId, compute);
             const creationPromise = observeGraphileBuild({
                 cacheKey: key,
                 serviceKey: key,

package/esm/middleware/mask-error.js

@@ -51,7 +51,7 @@ const BAD_USER_INPUT = 'BAD_USER_INPUT';
  * 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) => {
+export const normalizeError = (error) => {
     const original = error.originalError;
     const fromOriginal = original ? parse(original) : null;
     const parsed = fromOriginal?.code ? fromOriginal : parse(error);

package/esm/plugins/error-events-plugin.js

@@ -0,0 +1,76 @@
+import '../middleware/types'; // for Request type
+import { Logger } from '@pgpmjs/logger';
+import { getOperationAST } from 'graphql';
+import { escapeIdentifier } from 'pg';
+import { withPgClient } from 'pg-query-context';
+import { normalizeError } from '../middleware/mask-error';
+const log = new Logger('error-events');
+export const GRAPHQL_ERROR_EVENT = 'graphql.error';
+const getExpressRequest = (requestContext) => requestContext?.expressv4?.req;
+/**
+ * The first structured, public-classified registry code among the errors.
+ * Internal/unknown errors are bugs, not refusals: they are masked and logged
+ * by `maskError` and never recorded as tenant events.
+ */
+const refusalCode = (errors) => {
+    for (const error of errors ?? []) {
+        const { code, class: errorClass } = normalizeError(error);
+        if (code && errorClass === 'public')
+            return code;
+    }
+    return undefined;
+};
+export const recordEventSql = (events) => `SELECT ${escapeIdentifier(events.privateSchemaName)}.${escapeIdentifier(events.recordEvent)}($1, $2::uuid, $3::jsonb)`;
+/**
+ * Records `graphql.error` when an authenticated mutation is refused with a
+ * structured registry code. The refusal rolled back the mutation's own
+ * transaction, so the event is written afterwards in a fresh transaction under
+ * the same request claims, via the tenant's events module `record_event`.
+ *
+ * The server carries no policy about what a code means: the database reads
+ * `payload->>'code'` (e.g. PRINCIPAL_CHILD_WIDENS demoting a principal on the
+ * trust ladder). Endpoints without an events module record nothing.
+ * Unauthenticated requests are never recorded, so anonymous traffic cannot
+ * drive writes. The client response is never altered.
+ */
+export const createErrorEventsPlugin = (pool) => ({
+    name: 'ErrorEventsPlugin',
+    version: '0.0.0',
+    description: 'Records graphql.error through the tenant events module when an authenticated mutation is refused.',
+    grafast: {
+        middleware: {
+            async execute(next, event) {
+                const result = await next();
+                if (Symbol.asyncIterator in result)
+                    return result;
+                const { args } = event;
+                const req = getExpressRequest(args.requestContext);
+                const actorId = req?.token?.principal_id ?? req?.token?.user_id;
+                if (!actorId)
+                    return result;
+                if (getOperationAST(args.document, args.operationName)?.operation !== 'mutation')
+                    return result;
+                const code = refusalCode(result.errors);
+                if (!code)
+                    return result;
+                const pgSettings = args.contextValue?.pgSettings;
+                const label = req.requestId ? `[${req.requestId}]` : '[req]';
+                try {
+                    const events = await req.constructive?.useModule('events');
+                    if (!events || !pgSettings)
+                        return result;
+                    const operation = args.operationName ?? getOperationAST(args.document)?.name?.value ?? null;
+                    await withPgClient(pool, pgSettings, (client) => client.query(recordEventSql(events), [
+                        GRAPHQL_ERROR_EVENT,
+                        actorId,
+                        JSON.stringify({ code, operation })
+                    ]));
+                }
+                catch (err) {
+                    log.error(`${label} failed to record ${GRAPHQL_ERROR_EVENT} (${code}) for ${actorId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return result;
+            }
+        }
+    }
+});

package/esm/server.js

@@ -23,7 +23,7 @@ import { parseCookieValue, SESSION_COOKIE_NAME } from './middleware/cookie';
 import { cors } from './middleware/cors';
 import { errorHandler, notFoundHandler } from './middleware/error-handler';
 import { favicon } from './middleware/favicon';
-import { flush, flushService } from './middleware/flush';
+import { createFlushMiddleware, flushService } from './middleware/flush';
 import { createFnRouter } from './middleware/fn';
 import { graphile } from './middleware/graphile';
 import { multipartBridge } from './middleware/multipart-bridge';
@@ -191,7 +191,7 @@ class Server {
         // REST function invocation routes (POST /fn/:alias, GET /fn/invocations/:id)
         app.use(createFnRouter());
         app.use(graphile(effectiveOpts));
-        app.use(flush);
+        app.use(createFlushMiddleware(effectiveOpts));
         // Error handling - MUST be LAST
         app.use(notFoundHandler); // Catches unmatched routes (404)
         app.use(errorHandler); // Catches all thrown errors

package/index.d.ts

@@ -2,5 +2,5 @@ export * from './server';
 export { createApiMiddleware, getApiConfig, getSubdomain } from './middleware/api';
 export { createAuthenticateMiddleware } from './middleware/auth';
 export { cors } from './middleware/cors';
-export { flush, flushService } from './middleware/flush';
+export { createFlushMiddleware, flushService } from './middleware/flush';
 export { graphile } from './middleware/graphile';

package/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.graphile = exports.flushService = exports.flush = exports.cors = exports.createAuthenticateMiddleware = exports.getSubdomain = exports.getApiConfig = exports.createApiMiddleware = void 0;
+exports.graphile = exports.flushService = exports.createFlushMiddleware = exports.cors = exports.createAuthenticateMiddleware = exports.getSubdomain = exports.getApiConfig = exports.createApiMiddleware = void 0;
 __exportStar(require("./server"), exports);
 // Export middleware for use in testing packages
 var api_1 = require("./middleware/api");
@@ -26,7 +26,7 @@ Object.defineProperty(exports, "createAuthenticateMiddleware", { enumerable: tru
 var cors_1 = require("./middleware/cors");
 Object.defineProperty(exports, "cors", { enumerable: true, get: function () { return cors_1.cors; } });
 var flush_1 = require("./middleware/flush");
-Object.defineProperty(exports, "flush", { enumerable: true, get: function () { return flush_1.flush; } });
+Object.defineProperty(exports, "createFlushMiddleware", { enumerable: true, get: function () { return flush_1.createFlushMiddleware; } });
 Object.defineProperty(exports, "flushService", { enumerable: true, get: function () { return flush_1.flushService; } });
 var graphile_1 = require("./middleware/graphile");
 Object.defineProperty(exports, "graphile", { enumerable: true, get: function () { return graphile_1.graphile; } });

package/middleware/flush.d.ts

@@ -1,5 +1,11 @@
 import './types';
 import { ConstructiveOptions } from '@constructive-io/graphql-types';
-import { NextFunction, Request, Response } from 'express';
-export declare const flush: (req: Request, res: Response, next: NextFunction) => Promise<void>;
+import { RequestHandler } from 'express';
+/**
+ * `/flush` drops the routing and schema caches for the request's service key,
+ * so it is a control-plane operation: it needs the flush secret, not a tenant
+ * session. Without a configured secret there is no way to authenticate the
+ * caller, so the route stays closed.
+ */
+export declare const createFlushMiddleware: (opts: ConstructiveOptions) => RequestHandler;
 export declare const flushService: (opts: ConstructiveOptions, databaseId: string) => Promise<void>;

package/middleware/flush.js

@@ -1,24 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.flushService = exports.flush = void 0;
+exports.flushService = exports.createFlushMiddleware = void 0;
 require("./types"); // for Request type
 const logger_1 = require("@pgpmjs/logger");
 const server_utils_1 = require("@pgpmjs/server-utils");
+const crypto_1 = require("crypto");
 const graphile_cache_1 = require("graphile-cache");
 const pg_cache_1 = require("pg-cache");
 const routing_1 = require("./routing");
 const log = new logger_1.Logger('flush');
-const flush = async (req, res, next) => {
-    if (req.url === '/flush') {
-        // TODO: check bearer for a flush / special key
+const bearerToken = (req) => {
+    const header = req.get('authorization');
+    if (!header)
+        return null;
+    const [scheme, ...rest] = header.trim().split(/\s+/);
+    if (scheme.toLowerCase() !== 'bearer' || rest.length !== 1)
+        return null;
+    return rest[0];
+};
+// Compare digests rather than the tokens themselves: timingSafeEqual requires
+// equal lengths, and digests are equal-length whatever the caller presents.
+const tokensMatch = (presented, expected) => (0, crypto_1.timingSafeEqual)((0, crypto_1.createHash)('sha256').update(presented).digest(), (0, crypto_1.createHash)('sha256').update(expected).digest());
+/**
+ * `/flush` drops the routing and schema caches for the request's service key,
+ * so it is a control-plane operation: it needs the flush secret, not a tenant
+ * session. Without a configured secret there is no way to authenticate the
+ * caller, so the route stays closed.
+ */
+const createFlushMiddleware = (opts) => {
+    const expected = opts.api?.flushToken;
+    return async (req, res, next) => {
+        if (req.url !== '/flush') {
+            return next();
+        }
+        if (!expected) {
+            log.warn('[flush] rejected: no api.flushToken configured');
+            res.status(404).send('Not Found');
+            return;
+        }
+        const presented = bearerToken(req);
+        if (!presented || !tokensMatch(presented, expected)) {
+            log.warn('[flush] rejected: invalid or missing bearer token');
+            res.status(401).send('Unauthorized');
+            return;
+        }
         graphile_cache_1.graphileCache.delete(req.svc_key);
         server_utils_1.svcCache.delete(req.svc_key);
         res.status(200).send('OK');
-        return;
-    }
-    return next();
+    };
 };
-exports.flush = flush;
+exports.createFlushMiddleware = createFlushMiddleware;
 const flushService = async (opts, databaseId) => {
     const pgPool = (0, pg_cache_1.getPgPool)(opts.pg);
     log.info('flushing db ' + databaseId);

package/middleware/graphile.js

@@ -18,6 +18,7 @@ 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 error_events_plugin_1 = require("../plugins/error-events-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");
@@ -61,12 +62,13 @@ const reqLabel = (req) => (req.requestId ? `[${req.requestId}]` : '[req]');
  * plugin preset.  Without settings the default preset is used
  * (everything on except aggregates).
  */
-const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId, compute) => {
+const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, databaseSettings, apiId, compute) => {
     return {
         extends: [(0, graphile_settings_1.createConstructivePreset)(databaseSettings)],
         plugins: [
             auth_cookie_plugin_1.AuthCookiePlugin,
             request_protection_plugin_1.RequestProtectionPlugin,
+            (0, error_events_plugin_1.createErrorEventsPlugin)(pool),
             // 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
@@ -90,7 +92,15 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
         pgServices: [
             (0, graphile_settings_1.makePgService)({
                 pool,
-                schemas
+                schemas,
+                // Introspection runs outside any request, so it has no served role to
+                // inherit: unset, it reads the catalog as whatever role the pool
+                // connected as (a superuser in most deployments) and the schema
+                // advertises that role's reach. Naming the role keeps schema shape
+                // tied to a bounded role's grants.
+                ...(introspectionRole && {
+                    pgSettingsForIntrospection: { role: introspectionRole }
+                })
             })
         ],
         grafserv: {
@@ -145,6 +155,15 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                         if (req.token.session_id) {
                             pgSettings['jwt.claims.session_id'] = req.token.session_id;
                         }
+                        if (req.token.root_session_id) {
+                            pgSettings['jwt.claims.root_session_id'] = req.token.root_session_id;
+                        }
+                        if (req.token.parent_session_id) {
+                            pgSettings['jwt.claims.parent_session_id'] = req.token.parent_session_id;
+                        }
+                        if (req.token.intent) {
+                            pgSettings['jwt.claims.intent'] = req.token.intent;
+                        }
                         // Propagate credential metadata as JWT claims so PG functions
                         // can read them via current_setting('jwt.claims.access_level') etc.
                         if (req.token.access_level) {
@@ -293,7 +312,7 @@ const graphile = (opts) => {
             const pool = (0, pg_cache_1.getPgPool)(pgConfig);
             // Create promise and store in in-flight map BEFORE try block
             const compute = api.apiId ? await req.constructive?.useModule('compute') : undefined;
-            const preset = buildPreset(pool, schema || [], anonRole, roleName, api.databaseSettings, api.apiId, compute);
+            const preset = buildPreset(pool, schema || [], anonRole, roleName, opts.api?.introspectionRole, api.databaseSettings, api.apiId, compute);
             const creationPromise = (0, graphile_build_stats_1.observeGraphileBuild)({
                 cacheKey: key,
                 serviceKey: key,

package/middleware/mask-error.d.ts

@@ -1,4 +1,18 @@
+import { type ErrorContext } from '@constructive-io/errors';
 import { type GraphQLError, type GraphQLFormattedError } from 'graphql';
+/**
+ * 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.
+ */
+export declare const normalizeError: (error: GraphQLError) => {
+    code: string | null;
+    context: ErrorContext;
+    class: "public" | "internal";
+};
 /**
  * Production-aware error handling backed by `@constructive-io/errors`.
  *

package/middleware/mask-error.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.maskError = void 0;
+exports.maskError = exports.normalizeError = void 0;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const errors_1 = require("@constructive-io/errors");
 const env_1 = require("@pgpmjs/env");
@@ -63,6 +63,7 @@ const normalizeError = (error) => {
     const parsed = fromOriginal?.code ? fromOriginal : (0, errors_1.parse)(error);
     return { code: parsed.code, context: parsed.context, class: parsed.class };
 };
+exports.normalizeError = normalizeError;
 /**
  * Production-aware error handling backed by `@constructive-io/errors`.
  *
@@ -75,7 +76,7 @@ const normalizeError = (error) => {
  *    the original.
  */
 const maskError = (error) => {
-    const { code, context, class: errorClass } = normalizeError(error);
+    const { code, context, class: errorClass } = (0, exports.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).

package/middleware/types.d.ts

@@ -7,6 +7,9 @@ export type ConstructiveAPIToken = {
     session_id?: string;
     access_level?: string;
     kind?: string;
+    root_session_id?: string;
+    parent_session_id?: string;
+    intent?: string;
     [key: string]: unknown;
 };
 declare global {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.21.0",
+  "version": "5.23.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.12.0",
-    "@constructive-io/express-context": "^0.27.0",
-    "@constructive-io/graphql-env": "^3.31.3",
-    "@constructive-io/graphql-types": "^3.30.3",
+    "@constructive-io/errors": "^0.13.0",
+    "@constructive-io/express-context": "^0.29.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.4",
+    "@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.3",
+    "@pgpmjs/env": "^2.43.4",
     "@pgpmjs/logger": "^2.25.1",
-    "@pgpmjs/server-utils": "^3.27.3",
-    "@pgpmjs/types": "^2.53.1",
+    "@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.3",
+    "graphile-cache": "^4.12.4",
     "graphile-config": "1.1.0",
-    "graphile-function-bindings": "^1.14.4",
-    "graphile-settings": "^6.21.4",
+    "graphile-function-bindings": "^1.14.5",
+    "graphile-settings": "^6.21.6",
     "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.3",
+    "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.4",
+    "graphile-test": "5.14.5",
     "makage": "^0.8.0",
     "nodemon": "^3.1.14",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "6e2d71a9eb4e1f49f0de0b2b594b2f811de97442"
+  "gitHead": "86896399e80595be179738d459106cfbfbada659"
 }

package/plugins/error-events-plugin.d.ts

@@ -0,0 +1,19 @@
+import '../middleware/types';
+import type { EventsConfig } from '@constructive-io/express-context';
+import type { GraphileConfig } from 'graphile-config';
+import { type Pool } from 'pg';
+export declare const GRAPHQL_ERROR_EVENT = "graphql.error";
+export declare const recordEventSql: (events: EventsConfig) => string;
+/**
+ * Records `graphql.error` when an authenticated mutation is refused with a
+ * structured registry code. The refusal rolled back the mutation's own
+ * transaction, so the event is written afterwards in a fresh transaction under
+ * the same request claims, via the tenant's events module `record_event`.
+ *
+ * The server carries no policy about what a code means: the database reads
+ * `payload->>'code'` (e.g. PRINCIPAL_CHILD_WIDENS demoting a principal on the
+ * trust ladder). Endpoints without an events module record nothing.
+ * Unauthenticated requests are never recorded, so anonymous traffic cannot
+ * drive writes. The client response is never altered.
+ */
+export declare const createErrorEventsPlugin: (pool: Pool) => GraphileConfig.Plugin;

package/plugins/error-events-plugin.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createErrorEventsPlugin = exports.recordEventSql = exports.GRAPHQL_ERROR_EVENT = void 0;
+require("../middleware/types"); // for Request type
+const logger_1 = require("@pgpmjs/logger");
+const graphql_1 = require("graphql");
+const pg_1 = require("pg");
+const pg_query_context_1 = require("pg-query-context");
+const mask_error_1 = require("../middleware/mask-error");
+const log = new logger_1.Logger('error-events');
+exports.GRAPHQL_ERROR_EVENT = 'graphql.error';
+const getExpressRequest = (requestContext) => requestContext?.expressv4?.req;
+/**
+ * The first structured, public-classified registry code among the errors.
+ * Internal/unknown errors are bugs, not refusals: they are masked and logged
+ * by `maskError` and never recorded as tenant events.
+ */
+const refusalCode = (errors) => {
+    for (const error of errors ?? []) {
+        const { code, class: errorClass } = (0, mask_error_1.normalizeError)(error);
+        if (code && errorClass === 'public')
+            return code;
+    }
+    return undefined;
+};
+const recordEventSql = (events) => `SELECT ${(0, pg_1.escapeIdentifier)(events.privateSchemaName)}.${(0, pg_1.escapeIdentifier)(events.recordEvent)}($1, $2::uuid, $3::jsonb)`;
+exports.recordEventSql = recordEventSql;
+/**
+ * Records `graphql.error` when an authenticated mutation is refused with a
+ * structured registry code. The refusal rolled back the mutation's own
+ * transaction, so the event is written afterwards in a fresh transaction under
+ * the same request claims, via the tenant's events module `record_event`.
+ *
+ * The server carries no policy about what a code means: the database reads
+ * `payload->>'code'` (e.g. PRINCIPAL_CHILD_WIDENS demoting a principal on the
+ * trust ladder). Endpoints without an events module record nothing.
+ * Unauthenticated requests are never recorded, so anonymous traffic cannot
+ * drive writes. The client response is never altered.
+ */
+const createErrorEventsPlugin = (pool) => ({
+    name: 'ErrorEventsPlugin',
+    version: '0.0.0',
+    description: 'Records graphql.error through the tenant events module when an authenticated mutation is refused.',
+    grafast: {
+        middleware: {
+            async execute(next, event) {
+                const result = await next();
+                if (Symbol.asyncIterator in result)
+                    return result;
+                const { args } = event;
+                const req = getExpressRequest(args.requestContext);
+                const actorId = req?.token?.principal_id ?? req?.token?.user_id;
+                if (!actorId)
+                    return result;
+                if ((0, graphql_1.getOperationAST)(args.document, args.operationName)?.operation !== 'mutation')
+                    return result;
+                const code = refusalCode(result.errors);
+                if (!code)
+                    return result;
+                const pgSettings = args.contextValue?.pgSettings;
+                const label = req.requestId ? `[${req.requestId}]` : '[req]';
+                try {
+                    const events = await req.constructive?.useModule('events');
+                    if (!events || !pgSettings)
+                        return result;
+                    const operation = args.operationName ?? (0, graphql_1.getOperationAST)(args.document)?.name?.value ?? null;
+                    await (0, pg_query_context_1.withPgClient)(pool, pgSettings, (client) => client.query((0, exports.recordEventSql)(events), [
+                        exports.GRAPHQL_ERROR_EVENT,
+                        actorId,
+                        JSON.stringify({ code, operation })
+                    ]));
+                }
+                catch (err) {
+                    log.error(`${label} failed to record ${exports.GRAPHQL_ERROR_EVENT} (${code}) for ${actorId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return result;
+            }
+        }
+    }
+});
+exports.createErrorEventsPlugin = createErrorEventsPlugin;

package/server.js

@@ -198,7 +198,7 @@ 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