@constructive-io/graphql-server 5.20.8 → 5.21.0

package/middleware/admission-control.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdmissionControlMiddleware = void 0;
+require("./types"); // for Request type
+const errors_1 = require("@constructive-io/errors");
+const express_context_1 = require("@constructive-io/express-context");
+const logger_1 = require("@pgpmjs/logger");
+const graphql_response_1 = require("../errors/graphql-response");
+const recorder_1 = require("../refusals/recorder");
+const log = new logger_1.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 ?? express_context_1.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 = (0, express_context_1.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.
+ */
+const createAdmissionControlMiddleware = (options = {}) => {
+    const concurrency = new express_context_1.ConcurrencyLimiter();
+    const rate = new express_context_1.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 = (0, express_context_1.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)}`);
+            (0, recorder_1.recordRefusal)(req, 'rate_limited', { sourceIp: ip });
+            (0, graphql_response_1.respondWithGraphQLError)(res, errors_1.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`);
+            (0, recorder_1.recordRefusal)(req, lease.refusal === 'queue_timeout' ? 'queue_timeout' : 'concurrency_saturated', {
+                sourceIp: ip
+            });
+            (0, graphql_response_1.respondWithGraphQLError)(res, errors_1.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();
+    };
+};
+exports.createAdmissionControlMiddleware = createAdmissionControlMiddleware;

package/middleware/api.js

@@ -149,8 +149,8 @@ exports.getSvcKey = getSvcKey;
 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: (0, routing_1.requireApiRole)('anon_role', row.anon_role, row.api_id),
+    roleName: (0, routing_1.requireApiRole)('role_name', row.role_name, row.api_id),
     schema: row.schemas || [],
     rlsModule: settings.rlsModule,
     domains: [],
@@ -354,6 +354,11 @@ const createApiMiddleware = (opts) => {
                 res.status(404).send((0, _404_message_1.default)(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(_50x_1.default);
+                return;
+            }
             if (err.code === 'NO_DATABASE_ID') {
                 log.error('[api-middleware] no database id resolved:', err.message);
                 res.status(500).send(_50x_1.default);

package/middleware/request-protection.js

@@ -5,6 +5,7 @@ require("./types"); // for Request type
 const errors_1 = require("@constructive-io/errors");
 const express_context_1 = require("@constructive-io/express-context");
 const graphql_response_1 = require("../errors/graphql-response");
+const recorder_1 = require("../refusals/recorder");
 /**
  * Resolve the bounds this request runs under and attach them to it.
  *
@@ -54,6 +55,7 @@ const createRequestProtectionMiddleware = () => {
         if (Number.isFinite(declaredLength) &&
             declaredLength > protection.maxRequestBytes &&
             !isMultipart(req)) {
+            (0, recorder_1.recordRefusal)(req, 'request_too_large');
             (0, graphql_response_1.respondWithGraphQLError)(res, errors_1.errors.REQUEST_TOO_LARGE({ bytes: declaredLength, limit: protection.maxRequestBytes }));
             return;
         }

package/middleware/routing.d.ts

@@ -1,5 +1,11 @@
 import { Pool } from 'pg';
 import { ApiOptions, ApiStructure } from '../types';
+/**
+ * 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 declare const requireApiRole: (column: "role_name" | "anon_role", value: string | null | undefined, apiId: string | undefined) => string;
 /** Row shape returned by <schema>.resolve_route() — frozen DB↔server contract. */
 export interface ResolvedRoute {
     route_binding_id: string | null;

package/middleware/routing.js

@@ -1,8 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.routeToApiStructure = exports.resolveRoute = exports.isValidSchemaName = exports.getRoutingSchema = exports.DEFAULT_ROUTING_SCHEMA = void 0;
+exports.routeToApiStructure = exports.resolveRoute = exports.isValidSchemaName = exports.getRoutingSchema = exports.DEFAULT_ROUTING_SCHEMA = exports.requireApiRole = void 0;
 const logger_1 = require("@pgpmjs/logger");
 const log = new logger_1.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.
+ */
+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;
+};
+exports.requireApiRole = requireApiRole;
 const RESOLVER_FUNCTION = 'resolve_route';
 /** Published logical name of the database-scope routing plane. */
 exports.DEFAULT_ROUTING_SCHEMA = 'routing_public';
@@ -58,13 +87,14 @@ 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: (0, exports.requireApiRole)('anon_role', config.anon_role, apiId),
+        roleName: (0, exports.requireApiRole)('role_name', config.role_name, apiId),
         schema: config.schemas,
         domains: [],
         databaseId: config.database_id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-server",
-  "version": "5.20.8",
+  "version": "5.21.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Constructive GraphQL Server",
   "main": "index.js",
@@ -43,19 +43,19 @@
   "dependencies": {
     "@agentic-kit/ollama": "2.14.0",
     "@constructive-io/csrf": "^0.29.1",
-    "@constructive-io/errors": "^0.11.2",
-    "@constructive-io/express-context": "^0.26.2",
-    "@constructive-io/graphql-env": "^3.31.2",
-    "@constructive-io/graphql-types": "^3.30.2",
+    "@constructive-io/errors": "^0.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/llm-env": "^0.14.1",
-    "@constructive-io/query-builder": "^3.13.3",
+    "@constructive-io/query-builder": "^3.13.4",
     "@constructive-io/s3-utils": "^2.33.0",
     "@constructive-io/url-domains": "^2.30.1",
     "@graphile-contrib/pg-many-to-many": "2.0.0-rc.2",
-    "@pgpmjs/env": "^2.43.2",
+    "@pgpmjs/env": "^2.43.3",
     "@pgpmjs/logger": "^2.25.1",
-    "@pgpmjs/server-utils": "^3.27.2",
-    "@pgpmjs/types": "^2.53.0",
+    "@pgpmjs/server-utils": "^3.27.3",
+    "@pgpmjs/types": "^2.53.1",
     "cors": "^2.8.6",
     "deepmerge": "^4.3.1",
     "express": "^5.2.1",
@@ -64,16 +64,16 @@
     "grafserv": "1.0.1",
     "graphile-build": "5.1.1",
     "graphile-build-pg": "5.1.3",
-    "graphile-cache": "^4.12.2",
+    "graphile-cache": "^4.12.3",
     "graphile-config": "1.1.0",
-    "graphile-function-bindings": "^1.14.3",
-    "graphile-settings": "^6.21.3",
+    "graphile-function-bindings": "^1.14.4",
+    "graphile-settings": "^6.21.4",
     "graphile-utils": "5.0.3",
     "graphql": "16.13.0",
     "graphql-upload": "^13.0.0",
     "lru-cache": "^11.2.7",
     "pg": "^8.21.0",
-    "pg-cache": "^3.27.2",
+    "pg-cache": "^3.27.3",
     "pg-env": "^1.31.1",
     "pg-query-context": "^2.30.1",
     "pg-sql2": "5.0.1",
@@ -90,11 +90,11 @@
     "@types/request-ip": "^0.0.41",
     "@types/supertest": "^7.2.1",
     "cookie-parser": "^1.4.7",
-    "graphile-test": "5.14.3",
+    "graphile-test": "5.14.4",
     "makage": "^0.8.0",
     "nodemon": "^3.1.14",
     "supertest": "^7.2.2",
     "ts-node": "^10.9.2"
   },
-  "gitHead": "4deb5b9a00ead37453857d24274007255092822e"
+  "gitHead": "6e2d71a9eb4e1f49f0de0b2b594b2f811de97442"
 }

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

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

package/plugins/request-protection-plugin.js

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

package/refusals/recorder.d.ts

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

package/refusals/recorder.js

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

package/server.d.ts

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