@constructive-io/graphql-server 5.20.8 → 5.22.0

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

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

package/index.js

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

package/middleware/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;

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/flush.d.ts

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

package/middleware/flush.js

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

package/middleware/graphile.js

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

package/middleware/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/middleware/types.d.ts

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