@constructive-io/graphql-server 5.20.7 → 5.21.0

package/diagnostics/debug-memory-snapshot.d.ts

@@ -1,6 +1,7 @@
 import v8 from 'node:v8';
 import { getCacheStats } from 'graphile-cache';
 import { getGraphileBuildStats } from '../middleware/observability/graphile-build-stats';
+import { getRefusalRecorderStats } from '../refusals/recorder';
 export interface DebugMemorySnapshot {
     pid: number;
     nodeEnv: string | undefined;
@@ -47,6 +48,8 @@ export interface DebugMemorySnapshot {
         keys: string[];
     };
     graphileBuilds: ReturnType<typeof getGraphileBuildStats>;
+    /** In-memory refusal counter + flusher state; null when no recorder is installed. */
+    refusals: ReturnType<typeof getRefusalRecorderStats>;
     uptimeMinutes: number;
     timestamp: string;
 }

package/diagnostics/debug-memory-snapshot.js

@@ -10,6 +10,7 @@ const server_utils_1 = require("@pgpmjs/server-utils");
 const graphile_cache_1 = require("graphile-cache");
 const graphile_1 = require("../middleware/graphile");
 const graphile_build_stats_1 = require("../middleware/observability/graphile-build-stats");
+const recorder_1 = require("../refusals/recorder");
 const toMB = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 const getDebugMemorySnapshot = () => {
     const mem = process.memoryUsage();
@@ -70,6 +71,7 @@ const getDebugMemorySnapshot = () => {
             keys: (0, graphile_1.getInFlightKeys)(),
         },
         graphileBuilds: (0, graphile_build_stats_1.getGraphileBuildStats)(),
+        refusals: (0, recorder_1.getRefusalRecorderStats)(),
         uptimeMinutes: process.uptime() / 60,
         timestamp: new Date().toISOString(),
     };

package/errors/graphql-response.d.ts

@@ -12,10 +12,24 @@
  */
 import type { ConstructiveError } from '@constructive-io/errors';
 import type { Response } from 'express';
+/** Transport-level overrides for a short-circuited response. */
+export interface GraphQLErrorResponseInit {
+    /**
+     * HTTP status to answer with, when 200 would hide the refusal from the
+     * machinery that has to act on it. Admission control is the case that needs
+     * it: the operation never reached the schema, and a client's backoff — and
+     * every proxy and load balancer between us — reads the status code, not a
+     * GraphQL error body.
+     */
+    status?: number;
+    /** Extra headers, e.g. `Retry-After` on a 429. */
+    headers?: Record<string, string>;
+}
 /**
  * Send a {@link ConstructiveError} as a GraphQL error response.
  *
- * Uses HTTP 200 per the GraphQL-over-HTTP convention: transport succeeded, the
- * operation did not. The error's own `http` hint travels in `extensions`.
+ * Defaults to HTTP 200 per the GraphQL-over-HTTP convention: transport
+ * succeeded, the operation did not. The error's own `http` hint travels in
+ * `extensions`.
  */
-export declare function respondWithGraphQLError(res: Response, error: ConstructiveError): void;
+export declare function respondWithGraphQLError(res: Response, error: ConstructiveError, init?: GraphQLErrorResponseInit): void;

package/errors/graphql-response.js

@@ -16,11 +16,14 @@ exports.respondWithGraphQLError = respondWithGraphQLError;
 /**
  * Send a {@link ConstructiveError} as a GraphQL error response.
  *
- * Uses HTTP 200 per the GraphQL-over-HTTP convention: transport succeeded, the
- * operation did not. The error's own `http` hint travels in `extensions`.
+ * Defaults to HTTP 200 per the GraphQL-over-HTTP convention: transport
+ * succeeded, the operation did not. The error's own `http` hint travels in
+ * `extensions`.
  */
-function respondWithGraphQLError(res, error) {
-    res.status(200).json({
+function respondWithGraphQLError(res, error, init = {}) {
+    if (init.headers)
+        res.set(init.headers);
+    res.status(init.status ?? 200).json({
         errors: [{ message: error.message, extensions: error.toExtensions() }],
     });
 }

package/esm/diagnostics/debug-memory-snapshot.js

@@ -4,6 +4,7 @@ import { SVC_CACHE_TTL_MS, svcCache } from '@pgpmjs/server-utils';
 import { getCacheStats } from 'graphile-cache';
 import { getInFlightCount, getInFlightKeys } from '../middleware/graphile';
 import { getGraphileBuildStats } from '../middleware/observability/graphile-build-stats';
+import { getRefusalRecorderStats } from '../refusals/recorder';
 const toMB = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 export const getDebugMemorySnapshot = () => {
     const mem = process.memoryUsage();
@@ -64,6 +65,7 @@ export const getDebugMemorySnapshot = () => {
             keys: getInFlightKeys(),
         },
         graphileBuilds: getGraphileBuildStats(),
+        refusals: getRefusalRecorderStats(),
         uptimeMinutes: process.uptime() / 60,
         timestamp: new Date().toISOString(),
     };

package/esm/errors/graphql-response.js

@@ -13,11 +13,14 @@
 /**
  * Send a {@link ConstructiveError} as a GraphQL error response.
  *
- * Uses HTTP 200 per the GraphQL-over-HTTP convention: transport succeeded, the
- * operation did not. The error's own `http` hint travels in `extensions`.
+ * Defaults to HTTP 200 per the GraphQL-over-HTTP convention: transport
+ * succeeded, the operation did not. The error's own `http` hint travels in
+ * `extensions`.
  */
-export function respondWithGraphQLError(res, error) {
-    res.status(200).json({
+export function respondWithGraphQLError(res, error, init = {}) {
+    if (init.headers)
+        res.set(init.headers);
+    res.status(init.status ?? 200).json({
         errors: [{ message: error.message, extensions: error.toExtensions() }],
     });
 }

package/esm/middleware/admission-control.js

@@ -0,0 +1,132 @@
+import './types'; // for Request type
+import { errors } from '@constructive-io/errors';
+import { clientIpFrom, ConcurrencyLimiter, DEFAULT_REQUEST_PROTECTION, RateWindow, trustedProxyHops } from '@constructive-io/express-context';
+import { Logger } from '@pgpmjs/logger';
+import { respondWithGraphQLError } from '../errors/graphql-response';
+import { recordRefusal } from '../refusals/recorder';
+const log = new Logger('admission');
+/**
+ * admission-control — the gate that decides whether a GraphQL request starts.
+ *
+ * The document gate rejects a *shape* and the timeout GUCs bound a *duration*;
+ * neither refuses a request that is individually reasonable. This does, on two
+ * axes:
+ *
+ *   1. **Concurrency**, per database. The thing being protected is this
+ *      process's PostgreSQL pool, so the counter is in-process and
+ *      `maxConcurrentRequests` is a per-replica budget — a cluster-wide number
+ *      would need shared state on the hot path to bound something that is not
+ *      shared. Over budget, a request waits up to `maxQueueWaitMs` for a slot
+ *      and is then refused; it never queues unbounded, because a queue that
+ *      outgrows the timeout is just latency with a memory cost.
+ *
+ *   2. **Rate**, per caller per route. Keyed on the client address rather than
+ *      the tenant, because a tenant-wide limit is spent *by* an anonymous
+ *      flood: exhausting it takes the tenant's own API down on the attacker's
+ *      behalf. This is abuse protection and fails closed, which is the opposite
+ *      of a billing quota (that serves and records overage) — the two must not
+ *      be conflated, and neither is a database write on the request path.
+ *
+ * @module middleware/admission-control
+ */
+/** Window the per-caller rate is counted over — `rateLimitRpm` is per minute. */
+const RATE_WINDOW_MS = 60_000;
+/** What a request is keyed by when it carries no resolved database. */
+const UNKNOWN_DATABASE = 'unknown';
+const protectionOf = (req) => req.requestProtection ?? DEFAULT_REQUEST_PROTECTION;
+/**
+ * The route half of the rate key.
+ *
+ * Per-route rather than per-request-line so a caller cannot spread a flood
+ * across query strings, and so a cheap route's traffic does not spend the
+ * budget an expensive one needs.
+ */
+const routeOf = (req) => `${req.method} ${req.baseUrl}${req.path}`;
+/** Seconds for a `Retry-After` header — the smallest honest whole number. */
+const retryAfterSeconds = (ms) => String(Math.max(Math.ceil(ms / 1000), 1));
+/**
+ * How far back through `X-Forwarded-For` to believe.
+ *
+ * `req.clientIp` and `req.ip` are both unusable as a limiter key here: this
+ * server sets `trust proxy` to a predicate that returns true unconditionally,
+ * and `request-ip` reads the *leftmost* forwarded entry regardless — so either
+ * one hands a caller a fresh key per request for the cost of a header. The
+ * fallback to 1 hop exists because the opposite failure is just as bad: behind
+ * an ingress with no hop count configured, every caller resolves to the
+ * ingress's address and one abuser throttles the whole tenant.
+ */
+const resolveHops = (req, configured) => {
+    if (typeof configured === 'number')
+        return configured;
+    const fromEnv = trustedProxyHops();
+    if (fromEnv > 0)
+        return fromEnv;
+    return req.app?.get('trust proxy') ? 1 : 0;
+};
+/**
+ * Rate-limit callers per route, then admit at most `maxConcurrentRequests` of
+ * them per database into the handler chain.
+ *
+ * Mount after `createRequestProtectionMiddleware` (which resolves the bounds
+ * this reads) and before the GraphQL handler. Order within the middleware
+ * matters: the rate check is O(1) and runs first, so a flood is refused
+ * without ever occupying a concurrency slot or waiting in its queue.
+ */
+export const createAdmissionControlMiddleware = (options = {}) => {
+    const concurrency = new ConcurrencyLimiter();
+    const rate = new RateWindow(RATE_WINDOW_MS);
+    return async (req, res, next) => {
+        const protection = protectionOf(req);
+        const databaseId = req.databaseId ?? UNKNOWN_DATABASE;
+        // ─── Per-caller rate ────────────────────────────────────────────────────
+        const hops = resolveHops(req, options.trustedProxyHops);
+        const ip = clientIpFrom(req, hops);
+        const rateKey = `${databaseId}\u0000${ip}\u0000${routeOf(req)}`;
+        if (!rate.admit(rateKey, protection.rateLimitRpm, protection.rateLimitBurst)) {
+            log.warn(`[admission] rate limit: database=${databaseId} ip=${ip} route=${routeOf(req)}`);
+            recordRefusal(req, 'rate_limited', { sourceIp: ip });
+            respondWithGraphQLError(res, errors.RATE_LIMITED(), {
+                status: 429,
+                headers: { 'Retry-After': retryAfterSeconds(rate.retryAfterMs(rateKey)) }
+            });
+            return;
+        }
+        // ─── Per-database concurrency ───────────────────────────────────────────
+        let lease;
+        try {
+            lease = await concurrency.acquire(databaseId, {
+                limit: protection.maxConcurrentRequests,
+                queueWaitMs: protection.maxQueueWaitMs
+            });
+        }
+        catch (e) {
+            next(e);
+            return;
+        }
+        if (!lease.granted) {
+            log.warn(`[admission] concurrency refused: database=${databaseId} ` +
+                `limit=${protection.maxConcurrentRequests} reason=${lease.refusal} waited=${lease.queuedMs}ms`);
+            recordRefusal(req, lease.refusal === 'queue_timeout' ? 'queue_timeout' : 'concurrency_saturated', {
+                sourceIp: ip
+            });
+            respondWithGraphQLError(res, errors.CONCURRENCY_LIMIT_REACHED({
+                limit: protection.maxConcurrentRequests,
+                waitedMs: lease.queuedMs
+            }), {
+                status: 429,
+                // The queue is the honest wait estimate: a slot freed sooner than
+                // this and the request would already have been admitted.
+                headers: { 'Retry-After': retryAfterSeconds(protection.maxQueueWaitMs) }
+            });
+            return;
+        }
+        // Release exactly once, whichever ends first. `close` covers the client
+        // that hangs up mid-flight — without it an aborted request holds its slot
+        // until the process restarts, and a client that retries on abort would
+        // drain the tenant's budget one leaked slot at a time. `release` is
+        // idempotent, so both listeners can fire.
+        res.on('close', () => lease.release());
+        res.on('finish', () => lease.release());
+        next();
+    };
+};

package/esm/middleware/api.js

@@ -6,7 +6,7 @@ import { svcCache } from '@pgpmjs/server-utils';
 import { getPgPool } from 'pg-cache';
 import errorPage50x from '../errors/50x';
 import errorPage404Message from '../errors/404-message';
-import { getRoutingSchema, isValidSchemaName, resolveRoute, routeToApiStructure } from './routing';
+import { getRoutingSchema, isValidSchemaName, requireApiRole, resolveRoute, routeToApiStructure } from './routing';
 const log = new Logger('api');
 // =============================================================================
 // Module Loader Registry (replaces inline SQL queries for per-db config)
@@ -141,8 +141,8 @@ export const getSvcKey = (opts, req) => {
 const toApiStructure = (row, opts, settings = {}) => ({
     apiId: row.api_id,
     dbname: row.dbname || opts.pg?.database || '',
-    anonRole: row.anon_role || 'anon',
-    roleName: row.role_name || 'authenticated',
+    anonRole: requireApiRole('anon_role', row.anon_role, row.api_id),
+    roleName: requireApiRole('role_name', row.role_name, row.api_id),
     schema: row.schemas || [],
     rlsModule: settings.rlsModule,
     domains: [],
@@ -345,6 +345,11 @@ export const createApiMiddleware = (opts) => {
                 res.status(404).send(errorPage404Message(err.message));
                 return;
             }
+            if (err.code === 'MISSING_API_ROLE') {
+                log.error('[api-middleware] resolved API row has no served role:', err.message);
+                res.status(500).send(errorPage50x);
+                return;
+            }
             if (err.code === 'NO_DATABASE_ID') {
                 log.error('[api-middleware] no database id resolved:', err.message);
                 res.status(500).send(errorPage50x);

package/esm/middleware/graphile.js

@@ -174,10 +174,16 @@ const buildPreset = (pool, schemas, anonRole, roleName, databaseSettings, apiId,
                             '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;
@@ -188,11 +194,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/esm/middleware/request-protection.js

@@ -2,6 +2,7 @@ import './types'; // for Request type
 import { errors } from '@constructive-io/errors';
 import { DEFAULT_REQUEST_PROTECTION } from '@constructive-io/express-context';
 import { respondWithGraphQLError } from '../errors/graphql-response';
+import { recordRefusal } from '../refusals/recorder';
 /**
  * Resolve the bounds this request runs under and attach them to it.
  *
@@ -51,6 +52,7 @@ export const createRequestProtectionMiddleware = () => {
         if (Number.isFinite(declaredLength) &&
             declaredLength > protection.maxRequestBytes &&
             !isMultipart(req)) {
+            recordRefusal(req, 'request_too_large');
             respondWithGraphQLError(res, errors.REQUEST_TOO_LARGE({ bytes: declaredLength, limit: protection.maxRequestBytes }));
             return;
         }

package/esm/middleware/routing.js

@@ -1,5 +1,33 @@
 import { Logger } from '@pgpmjs/logger';
 const log = new Logger('routing');
+// =============================================================================
+// Scoped routing plane (resolve_route contract)
+// =============================================================================
+//
+// One indexed call resolves an incoming request across scopes. The server's
+// projection is HOST-ONLY: Traefik/Ingress owns L7 path/method routing, so
+// the server always calls the frozen contract with the root path and no
+// method:
+//
+//   SELECT * FROM <schema>.resolve_route(request_host, '/', NULL)
+//
+// Contract (constructive-db docs/architecture/scoped-domain-routing.md):
+// a single row is always returned; no match → route_binding_id IS NULL.
+/**
+ * The role an API row names is the role the server will SET ROLE to; a row
+ * that leaves one blank is a broken surface, not a request for a default.
+ * Throws (code MISSING_API_ROLE) rather than substituting a role.
+ */
+export const requireApiRole = (column, value, apiId) => {
+    if (typeof value !== 'string' || value.trim() === '') {
+        const error = new Error(`API ${apiId ?? '<unknown>'} has no ${column}; a served role is required and there is no default.`);
+        error.code = 'MISSING_API_ROLE';
+        error.column = column;
+        error.apiId = apiId;
+        throw error;
+    }
+    return value;
+};
 const RESOLVER_FUNCTION = 'resolve_route';
 /** Published logical name of the database-scope routing plane. */
 export const DEFAULT_ROUTING_SCHEMA = 'routing_public';
@@ -52,13 +80,14 @@ export const routeToApiStructure = (route, opts) => {
         log.debug('[resolve-route] api target missing schemas in resolved_config; no match');
         return null;
     }
+    const apiId = config.api_id ?? route.target_source_id ?? undefined;
     return {
-        apiId: config.api_id ?? route.target_source_id ?? undefined,
+        apiId,
         // Scoped APIs leave dbname NULL when their schemas live in the serving
         // database; fall back to the server's own database in that case.
         dbname: config.dbname || opts.pg?.database || '',
-        anonRole: config.anon_role || 'anon',
-        roleName: config.role_name || 'authenticated',
+        anonRole: requireApiRole('anon_role', config.anon_role, apiId),
+        roleName: requireApiRole('role_name', config.role_name, apiId),
         schema: config.schemas,
         domains: [],
         databaseId: config.database_id,

package/esm/plugins/request-protection-plugin.js

@@ -1,6 +1,21 @@
 import '../middleware/types'; // for Request type
 import { DEFAULT_REQUEST_PROTECTION } from '@constructive-io/express-context';
+import { SafeError } from 'grafast';
 import { enforceDocumentProtection } from '../protection/document-gate';
+import { recordRefusal } from '../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. */
+export const documentRefusalReason = (err) => {
+    if (!(err instanceof SafeError))
+        return undefined;
+    const code = err.extensions?.code;
+    return typeof code === 'string' ? DOCUMENT_REFUSALS[code] : undefined;
+};
 /**
  * Get the Express request from a grafserv request context.
  */
@@ -31,7 +46,17 @@ export const RequestProtectionPlugin = {
                 // the platform defaults still apply rather than nothing at all.
                 const protection = req?.requestProtection ?? DEFAULT_REQUEST_PROTECTION;
                 if (args.document && args.schema) {
-                    enforceDocumentProtection(args.schema, args.document, args.variableValues, protection, args.operationName);
+                    try {
+                        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 = documentRefusalReason(err);
+                        if (reason && req)
+                            recordRefusal(req, reason);
+                        throw err;
+                    }
                 }
                 return next();
             }

package/esm/refusals/recorder.js

@@ -0,0 +1,136 @@
+import '../middleware/types'; // for Request type
+import { clientIpFrom, createRecordRefusalsSink, RefusalRecorder, trustedProxyHops } from '@constructive-io/express-context';
+import { Logger } from '@pgpmjs/logger';
+import { getPgPool } from 'pg-cache';
+const log = new 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. */
+export const PLATFORM_BOOTSTRAP_PRINCIPAL = 'platform-bootstrap';
+let installed = null;
+/** Make `recorder` the process's recorder. Returns the previous one, if any. */
+export const installRefusalRecorder = (recorder) => {
+    const previous = installed;
+    installed = recorder;
+    return previous;
+};
+export const getRefusalRecorder = () => installed;
+export const getRefusalRecorderStats = () => installed?.stats() ?? null;
+/** The route half of a refusal key — the same shape admission control keys on. */
+export const routeKeyOf = (req) => `${req.method} ${req.baseUrl ?? ''}${req.path ?? req.url ?? ''}`;
+/**
+ * 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 = 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.
+ */
+export 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: routeKeyOf(req),
+        sourceIp: opts.sourceIp !== undefined
+            ? opts.sourceIp
+            : 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)}`);
+    }
+};
+/**
+ * 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 const resolvePlatformFlushIdentity = async (pool, principalName = 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
+    };
+};
+export 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'
+});
+/**
+ * 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 const createPlatformRefusalRecorder = (opts, recorderOpts = {}) => {
+    const pool = getPgPool(opts.pg);
+    let cached = null;
+    const claims = async () => {
+        if (cached)
+            return cached;
+        cached = platformFlushClaims(await resolvePlatformFlushIdentity(pool, recorderOpts.principalName));
+        log.info(`[refusals] flushing as '${recorderOpts.principalName ?? PLATFORM_BOOTSTRAP_PRINCIPAL}'`);
+        return cached;
+    };
+    return new RefusalRecorder({
+        sink: createRecordRefusalsSink({ pool, claims }),
+        intervalMs: recorderOpts.intervalMs,
+        jitterMs: recorderOpts.jitterMs,
+        maxKeys: recorderOpts.maxKeys
+    });
+};

package/esm/server.js

@@ -14,6 +14,7 @@ import { createAgenticRouter } from './agentic';
 import { closeDebugDatabasePools } from './diagnostics/debug-db-snapshot';
 import { startDebugSampler } from './diagnostics/debug-sampler';
 import { isDevelopmentObservabilityMode, isGraphqlObservabilityEnabled, isGraphqlObservabilityRequested, isLoopbackHost } from './diagnostics/observability';
+import { createAdmissionControlMiddleware } from './middleware/admission-control';
 import { createApiMiddleware } from './middleware/api';
 import { createAuthenticateMiddleware } from './middleware/auth';
 // Auth cookie handling is done via AuthCookiePlugin in grafserv
@@ -32,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 { createPlatformRefusalRecorder, installRefusalRecorder } from './refusals/recorder';
 const log = new Logger('server');
 /**
  * Creates and starts a GraphQL server instance
@@ -69,6 +71,7 @@ class Server {
     closed = false;
     httpServer = null;
     debugSampler = null;
+    refusalRecorder = null;
     constructor(opts) {
         this.opts = getEnvOptions(opts);
         const effectiveOpts = this.opts;
@@ -146,6 +149,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(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', createAdmissionControlMiddleware());
         app.use(createCaptchaMiddleware());
         // CSRF protection for cookie-authenticated requests
         // Skip CSRF for Bearer token auth (not vulnerable to CSRF) and anonymous requests
@@ -187,6 +197,11 @@ class Server {
         app.use(errorHandler); // Catches all thrown errors
         this.app = app;
         this.debugSampler = observabilityEnabled ? 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 = createPlatformRefusalRecorder(effectiveOpts);
+        installRefusalRecorder(this.refusalRecorder);
+        this.refusalRecorder.start();
     }
     listen() {
         const { server } = this.opts;
@@ -291,6 +306,11 @@ class Server {
         this.closed = true;
         this.shuttingDown = true;
         await this.removeEventListener();
+        if (this.refusalRecorder) {
+            installRefusalRecorder(null);
+            await this.refusalRecorder.stop();
+            this.refusalRecorder = null;
+        }
         if (this.debugSampler) {
             await this.debugSampler.stop();
             this.debugSampler = null;

package/middleware/admission-control.d.ts

@@ -0,0 +1,20 @@
+import './types';
+import type { RequestHandler } from 'express';
+export interface AdmissionControlOptions {
+    /**
+     * How many proxies of our own sit in front of the server. Defaults to
+     * `TRUSTED_PROXY_HOPS`, then to 1 when Express is configured to trust a
+     * proxy at all; see `clientIpFrom` for why guessing higher is unsafe.
+     */
+    trustedProxyHops?: number;
+}
+/**
+ * Rate-limit callers per route, then admit at most `maxConcurrentRequests` of
+ * them per database into the handler chain.
+ *
+ * Mount after `createRequestProtectionMiddleware` (which resolves the bounds
+ * this reads) and before the GraphQL handler. Order within the middleware
+ * matters: the rate check is O(1) and runs first, so a flood is refused
+ * without ever occupying a concurrency slot or waiting in its queue.
+ */
+export declare const createAdmissionControlMiddleware: (options?: AdmissionControlOptions) => RequestHandler;