@constructive-io/graphql-server 5.23.0 → 5.25.0

package/esm/middleware/standing.js

@@ -0,0 +1,36 @@
+import './types'; // for Request type
+import { errors } from '@constructive-io/errors';
+import { respondWithGraphQLError } from '../errors/graphql-response';
+/**
+ * Express middleware that refuses requests pinned to a database that is not in
+ * good standing.
+ *
+ * The decision is the `standing` loader's (system-controlled
+ * `suspended_at`/`suspended_reason` on `metaschema_public.database`, cached for
+ * a few seconds), so an established client keeps being served for at most that
+ * window after a suspension. A database the plane does not know is refused the
+ * same way: a request pinned to it has nothing to run against. A lookup failure
+ * is handed to the error handler — "could not verify" is not "allowed".
+ *
+ * A request without a resolved database (no context, or a plane without
+ * `metaschema_public`) has nothing to be suspended and passes through.
+ *
+ * Mount after the context middleware and before the GraphQL handler.
+ */
+export const createStandingMiddleware = () => {
+    return async (req, res, next) => {
+        let standing;
+        try {
+            standing = await req.constructive?.useModule('standing');
+        }
+        catch (e) {
+            next(e);
+            return;
+        }
+        if (standing && (!standing.exists || standing.suspended)) {
+            respondWithGraphQLError(res, errors.ACCESS_SUSPENDED(standing.reason ? { reason: standing.reason } : {}), { status: 403 });
+            return;
+        }
+        next();
+    };
+};

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

@@ -5,7 +5,6 @@ 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.
@@ -20,23 +19,31 @@ const refusalCode = (errors) => {
     }
     return undefined;
 };
-export const recordEventSql = (events) => `SELECT ${escapeIdentifier(events.privateSchemaName)}.${escapeIdentifier(events.recordEvent)}($1, $2::uuid, $3::jsonb)`;
+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 `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`.
+ * 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 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.
+ * 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 graphql.error through the tenant events module when an authenticated mutation is refused.',
+    description: 'Records a refused authenticated mutation as its error code through the tenant events module.',
     grafast: {
         middleware: {
             async execute(next, event) {
@@ -60,14 +67,10 @@ export const createErrorEventsPlugin = (pool) => ({
                     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 })
-                    ]));
+                    await withPgClient(pool, pgSettings, (client) => client.query(recordErrorSql(events), [code, actorId, JSON.stringify({ operation })]));
                 }
                 catch (err) {
-                    log.error(`${label} failed to record ${GRAPHQL_ERROR_EVENT} (${code}) for ${actorId}: ${err instanceof Error ? err.message : String(err)}`);
+                    log.error(`${label} failed to record refusal ${code} for ${actorId}: ${err instanceof Error ? err.message : String(err)}`);
                 }
                 return result;
             }

package/esm/server.js

@@ -33,6 +33,7 @@ import { localObservabilityOnly } from './middleware/observability/guard';
 import { createRequestLogger } from './middleware/observability/request-logger';
 import { createRequestProtectionMiddleware } from './middleware/request-protection';
 import { getRoutingSchema } from './middleware/routing';
+import { createStandingMiddleware } from './middleware/standing';
 import { createPlatformRefusalRecorder, installRefusalRecorder } from './refusals/recorder';
 const log = new Logger('server');
 /**
@@ -146,6 +147,9 @@ class Server {
             loaders: createDefaultRegistry(),
             routingSchema: getRoutingSchema(effectiveOpts)
         }));
+        // A suspended (or unknown) database is refused before anything is spent on
+        // the request; billing and platform admins set that state, the loader reads it.
+        app.use(createStandingMiddleware());
         // 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(createRequestProtectionMiddleware());

package/middleware/standing.d.ts

@@ -0,0 +1,19 @@
+import './types';
+import type { RequestHandler } from 'express';
+/**
+ * Express middleware that refuses requests pinned to a database that is not in
+ * good standing.
+ *
+ * The decision is the `standing` loader's (system-controlled
+ * `suspended_at`/`suspended_reason` on `metaschema_public.database`, cached for
+ * a few seconds), so an established client keeps being served for at most that
+ * window after a suspension. A database the plane does not know is refused the
+ * same way: a request pinned to it has nothing to run against. A lookup failure
+ * is handed to the error handler — "could not verify" is not "allowed".
+ *
+ * A request without a resolved database (no context, or a plane without
+ * `metaschema_public`) has nothing to be suspended and passes through.
+ *
+ * Mount after the context middleware and before the GraphQL handler.
+ */
+export declare const createStandingMiddleware: () => RequestHandler;

package/middleware/standing.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStandingMiddleware = void 0;
+require("./types"); // for Request type
+const errors_1 = require("@constructive-io/errors");
+const graphql_response_1 = require("../errors/graphql-response");
+/**
+ * Express middleware that refuses requests pinned to a database that is not in
+ * good standing.
+ *
+ * The decision is the `standing` loader's (system-controlled
+ * `suspended_at`/`suspended_reason` on `metaschema_public.database`, cached for
+ * a few seconds), so an established client keeps being served for at most that
+ * window after a suspension. A database the plane does not know is refused the
+ * same way: a request pinned to it has nothing to run against. A lookup failure
+ * is handed to the error handler — "could not verify" is not "allowed".
+ *
+ * A request without a resolved database (no context, or a plane without
+ * `metaschema_public`) has nothing to be suspended and passes through.
+ *
+ * Mount after the context middleware and before the GraphQL handler.
+ */
+const createStandingMiddleware = () => {
+    return async (req, res, next) => {
+        let standing;
+        try {
+            standing = await req.constructive?.useModule('standing');
+        }
+        catch (e) {
+            next(e);
+            return;
+        }
+        if (standing && (!standing.exists || standing.suspended)) {
+            (0, graphql_response_1.respondWithGraphQLError)(res, errors_1.errors.ACCESS_SUSPENDED(standing.reason ? { reason: standing.reason } : {}), { status: 403 });
+            return;
+        }
+        next();
+    };
+};
+exports.createStandingMiddleware = createStandingMiddleware;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.23.0",
+  "version": "5.25.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.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/errors": "^0.14.0",
+    "@constructive-io/express-context": "^0.31.0",
+    "@constructive-io/graphql-env": "^3.32.1",
+    "@constructive-io/graphql-types": "^3.31.1",
     "@constructive-io/llm-env": "^0.14.1",
-    "@constructive-io/query-builder": "^3.13.5",
+    "@constructive-io/query-builder": "^3.13.6",
     "@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.4",
+    "@pgpmjs/env": "^2.43.5",
     "@pgpmjs/logger": "^2.25.1",
-    "@pgpmjs/server-utils": "^3.27.4",
-    "@pgpmjs/types": "^2.53.2",
+    "@pgpmjs/server-utils": "^3.27.5",
+    "@pgpmjs/types": "^2.53.3",
     "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.4",
+    "graphile-cache": "^4.12.5",
     "graphile-config": "1.1.0",
-    "graphile-function-bindings": "^1.14.5",
-    "graphile-settings": "^6.21.6",
+    "graphile-function-bindings": "^1.14.6",
+    "graphile-settings": "^6.21.8",
     "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.4",
+    "pg-cache": "^3.27.5",
     "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.5",
+    "graphile-test": "5.14.6",
     "makage": "^0.8.0",
     "nodemon": "^3.1.14",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "86896399e80595be179738d459106cfbfbada659"
+  "gitHead": "27be33dc1ba8351e2a2c2bbb99b9c0798c0813b9"
 }

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

@@ -2,18 +2,20 @@ 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;
+export declare const recordErrorSql: (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`.
+ * 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 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.
+ * 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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createErrorEventsPlugin = exports.recordEventSql = exports.GRAPHQL_ERROR_EVENT = void 0;
+exports.createErrorEventsPlugin = exports.recordErrorSql = void 0;
 require("../middleware/types"); // for Request type
 const logger_1 = require("@pgpmjs/logger");
 const graphql_1 = require("graphql");
@@ -8,7 +8,6 @@ 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.
@@ -23,24 +22,32 @@ const refusalCode = (errors) => {
     }
     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;
+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 `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`.
+ * 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 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.
+ * 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 graphql.error through the tenant events module when an authenticated mutation is refused.',
+    description: 'Records a refused authenticated mutation as its error code through the tenant events module.',
     grafast: {
         middleware: {
             async execute(next, event) {
@@ -64,14 +71,10 @@ const createErrorEventsPlugin = (pool) => ({
                     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 })
-                    ]));
+                    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 ${exports.GRAPHQL_ERROR_EVENT} (${code}) for ${actorId}: ${err instanceof Error ? err.message : String(err)}`);
+                    log.error(`${label} failed to record refusal ${code} for ${actorId}: ${err instanceof Error ? err.message : String(err)}`);
                 }
                 return result;
             }

package/server.js

@@ -39,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 standing_1 = require("./middleware/standing");
 const recorder_1 = require("./refusals/recorder");
 const log = new logger_1.Logger('server');
 /**
@@ -153,6 +154,9 @@ class Server {
             loaders: (0, express_context_1.createDefaultRegistry)(),
             routingSchema: (0, routing_1.getRoutingSchema)(effectiveOpts)
         }));
+        // A suspended (or unknown) database is refused before anything is spent on
+        // the request; billing and platform admins set that state, the loader reads it.
+        app.use((0, standing_1.createStandingMiddleware)());
         // 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)());