@constructive-io/graphql-server 5.22.0 → 5.24.0

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';
@@ -61,6 +62,7 @@ const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, datab
         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

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,79 @@
+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');
+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 recordErrorSql = (events) => {
+    if (!events.recordError) {
+        throw new Error(`events module ${events.privateSchemaName} has no record_error function`);
+    }
+    return `SELECT ${escapeIdentifier(events.privateSchemaName)}.${escapeIdentifier(events.recordError)}($1, $2::uuid, $3::jsonb)`;
+};
+/**
+ * Records a refused authenticated mutation as an event named after the error
+ * code raised by `errors.raise_error`. 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_error`, which classifies the code as an error that earns no ladder
+ * progress.
+ *
+ * The server carries no policy: the code is the event, and the database decides
+ * what it means — a ladder's `revoked_by` names the code directly (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 a refused authenticated mutation as its error code through the tenant events module.',
+    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(recordErrorSql(events), [code, actorId, JSON.stringify({ operation })]));
+                }
+                catch (err) {
+                    log.error(`${label} failed to record refusal ${code} for ${actorId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return result;
+            }
+        }
+    }
+});

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");
@@ -67,6 +68,7 @@ const buildPreset = (pool, schemas, anonRole, roleName, introspectionRole, datab
         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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.22.0",
+  "version": "5.24.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -44,7 +44,7 @@
     "@agentic-kit/ollama": "2.14.0",
     "@constructive-io/csrf": "^0.29.1",
     "@constructive-io/errors": "^0.13.0",
-    "@constructive-io/express-context": "^0.28.0",
+    "@constructive-io/express-context": "^0.30.0",
     "@constructive-io/graphql-env": "^3.32.0",
     "@constructive-io/graphql-types": "^3.31.0",
     "@constructive-io/llm-env": "^0.14.1",
@@ -67,7 +67,7 @@
     "graphile-cache": "^4.12.4",
     "graphile-config": "1.1.0",
     "graphile-function-bindings": "^1.14.5",
-    "graphile-settings": "^6.21.5",
+    "graphile-settings": "^6.21.7",
     "graphile-utils": "5.0.3",
     "graphql": "16.13.0",
     "graphql-upload": "^13.0.0",
@@ -96,5 +96,5 @@
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "01e073830677c0587bab564b7d575a06b5156f0c"
+  "gitHead": "10d3a11478d17a20c80da5a827f8e8da4facfc80"
 }

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

@@ -0,0 +1,21 @@
+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 recordErrorSql: (events: EventsConfig) => string;
+/**
+ * Records a refused authenticated mutation as an event named after the error
+ * code raised by `errors.raise_error`. 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_error`, which classifies the code as an error that earns no ladder
+ * progress.
+ *
+ * The server carries no policy: the code is the event, and the database decides
+ * what it means — a ladder's `revoked_by` names the code directly (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,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createErrorEventsPlugin = exports.recordErrorSql = 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');
+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 recordErrorSql = (events) => {
+    if (!events.recordError) {
+        throw new Error(`events module ${events.privateSchemaName} has no record_error function`);
+    }
+    return `SELECT ${(0, pg_1.escapeIdentifier)(events.privateSchemaName)}.${(0, pg_1.escapeIdentifier)(events.recordError)}($1, $2::uuid, $3::jsonb)`;
+};
+exports.recordErrorSql = recordErrorSql;
+/**
+ * Records a refused authenticated mutation as an event named after the error
+ * code raised by `errors.raise_error`. 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_error`, which classifies the code as an error that earns no ladder
+ * progress.
+ *
+ * The server carries no policy: the code is the event, and the database decides
+ * what it means — a ladder's `revoked_by` names the code directly (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 a refused authenticated mutation as its error code through the tenant events module.',
+    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.recordErrorSql)(events), [code, actorId, JSON.stringify({ operation })]));
+                }
+                catch (err) {
+                    log.error(`${label} failed to record refusal ${code} for ${actorId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return result;
+            }
+        }
+    }
+});
+exports.createErrorEventsPlugin = createErrorEventsPlugin;