@constructive-io/express-context 0.26.2 → 0.28.0

package/esm/refusals.js

@@ -0,0 +1,214 @@
+/**
+ * refusals — the refusal-observability instantiation of `usage-counter`.
+ *
+ * Every refusal the platform issues (a 429 from admission control, a 413 for an
+ * oversized body, a document-gate rejection, a gateway's route or IP window)
+ * is one `RefusalRecorder.record(...)` call at the point the response is
+ * written. That call is an in-memory increment and nothing else — no promise,
+ * no pool, no allocation beyond the key — so a flood costs a counter bump and
+ * refusing traffic keeps working when the recorder's store is down.
+ *
+ * Counts are keyed by `(minute, database, lane, reason, route, source /24)`,
+ * which is exactly the set of questions the platform table answers: which
+ * tenant, why, on which route, from which network, since when. Raw addresses
+ * are never part of the key; `sourceBucket` truncates to a /24 (v4) or /48
+ * (v6) before anything is counted.
+ *
+ * The flush writes the drained batch as one `record_refusals(jsonb)` call —
+ * one statement per window regardless of how many keys it holds.
+ *
+ * @module refusals
+ */
+import { Logger } from '@pgpmjs/logger';
+import { withPgClient } from 'pg-query-context';
+import { BoundedCounter, CounterFlusher } from './usage-counter';
+const log = new Logger('refusals');
+export const REFUSAL_REASONS = [
+    'rate_limited',
+    'concurrency_saturated',
+    'queue_timeout',
+    'request_too_large',
+    'query_too_deep',
+    'query_too_costly',
+    'page_size_too_large',
+    'anonymous_not_callable',
+    'route_rate_limited'
+];
+/** `source_bucket` when the lane could not resolve an address. */
+export const UNKNOWN_SOURCE = 'unknown';
+/** `source_bucket` / `route_key` of the fold-down entry once the counter is full. */
+export const OVERFLOW_SOURCE = 'overflow';
+export const OVERFLOW_ROUTE = '*';
+const MINUTE_MS = 60_000;
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/**
+ * Reduce a client address to a network prefix: `/24` for IPv4, `/48` for IPv6.
+ * Enough to tell "one network hammering an anonymous route" from "the tenant's
+ * own users"; not enough to be a person. Anything unparseable is `unknown`.
+ */
+export const sourceBucket = (ip) => {
+    if (!ip)
+        return UNKNOWN_SOURCE;
+    let addr = ip.trim();
+    if (addr.startsWith('[')) {
+        const end = addr.indexOf(']');
+        if (end === -1)
+            return UNKNOWN_SOURCE;
+        addr = addr.slice(1, end);
+    }
+    const zone = addr.indexOf('%');
+    if (zone !== -1)
+        addr = addr.slice(0, zone);
+    if (addr.toLowerCase().startsWith('::ffff:')) {
+        const mapped = addr.slice('::ffff:'.length);
+        if (IPV4.test(mapped))
+            addr = mapped;
+    }
+    const v4 = IPV4.exec(addr);
+    if (v4) {
+        const octets = v4.slice(1, 5).map(Number);
+        if (octets.some((o) => o > 255))
+            return UNKNOWN_SOURCE;
+        return `${octets[0]}.${octets[1]}.${octets[2]}.0/24`;
+    }
+    const groups = expandIpv6(addr);
+    if (!groups)
+        return UNKNOWN_SOURCE;
+    return `${groups[0]}:${groups[1]}:${groups[2]}::/48`;
+};
+/** The eight hextets of an IPv6 address, or null when it does not parse. */
+const expandIpv6 = (addr) => {
+    if (!/^[0-9a-fA-F:]+$/.test(addr) || addr.indexOf(':::') !== -1)
+        return null;
+    const halves = addr.split('::');
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(':') : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    const groups = [...head, ...Array(missing).fill('0'), ...tail];
+    if (groups.some((g) => g.length === 0 || g.length > 4))
+        return null;
+    return groups.map((g) => parseInt(g, 16).toString(16));
+};
+const minuteOf = (at) => Math.floor(at / MINUTE_MS) * MINUTE_MS;
+export const refusalKeyOf = (key) => `${key.minuteBucket}\u0000${key.databaseId ?? ''}\u0000${key.lane}\u0000${key.reason}\u0000${key.routeKey}\u0000${key.sourceBucket}`;
+/**
+ * Where a key folds to once the counter is full: same minute, tenant, lane and
+ * reason; route and source collapsed. A source-spraying flood therefore costs
+ * `maxKeys` entries plus one per `(database, lane, reason)`, the tenant/reason
+ * attribution is never lost, and the presence of an `overflow` row is itself
+ * the signal that a spray happened.
+ */
+export const refusalOverflowKey = (key) => ({
+    ...key,
+    routeKey: OVERFLOW_ROUTE,
+    sourceBucket: OVERFLOW_SOURCE
+});
+/** Shape a drained batch for `record_refusals(jsonb)`. */
+export const refusalRows = (entries) => entries.map(({ key, count, firstAt, lastAt }) => ({
+    minute_bucket: new Date(key.minuteBucket).toISOString(),
+    database_id: key.databaseId,
+    lane: key.lane,
+    reason: key.reason,
+    route_key: key.routeKey,
+    source_bucket: key.sourceBucket,
+    count,
+    first_seen_at: new Date(firstAt).toISOString(),
+    last_seen_at: new Date(lastAt).toISOString()
+}));
+export const DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = 10_000;
+export const DEFAULT_REFUSAL_FLUSH_JITTER_MS = 2_000;
+export const DEFAULT_REFUSAL_MAX_KEYS = 2_000;
+const defaultOnError = (err, dropped) => {
+    const refusals = dropped.reduce((sum, e) => sum + e.count, 0);
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(`[refusals] flush failed; dropped ${refusals} refusals across ${dropped.length} keys: ${message}`);
+};
+/**
+ * `BoundedCounter<RefusalKey>` + `CounterFlusher` + a `record_refusals` sink.
+ * Construct one per process, `start()` it, `record()` from every refusal site,
+ * `stop()` on shutdown.
+ */
+export class RefusalRecorder {
+    counter;
+    flusher;
+    recordFailures = 0;
+    constructor(opts) {
+        this.counter = new BoundedCounter({
+            maxKeys: opts.maxKeys ?? DEFAULT_REFUSAL_MAX_KEYS,
+            keyOf: refusalKeyOf,
+            overflowKey: refusalOverflowKey
+        });
+        this.flusher = new CounterFlusher(this.counter, (entries) => opts.sink(refusalRows(entries)), {
+            intervalMs: opts.intervalMs ?? DEFAULT_REFUSAL_FLUSH_INTERVAL_MS,
+            jitterMs: opts.jitterMs ?? DEFAULT_REFUSAL_FLUSH_JITTER_MS,
+            onError: opts.onError ?? defaultOnError
+        });
+    }
+    /**
+     * Count one refusal. Synchronous and never throws: the request that is
+     * being refused must finish being refused whatever state the recorder is in.
+     */
+    record(refusal) {
+        try {
+            const at = refusal.at ?? Date.now();
+            this.counter.increment({
+                minuteBucket: minuteOf(at),
+                databaseId: refusal.databaseId,
+                lane: refusal.lane,
+                reason: refusal.reason,
+                routeKey: refusal.routeKey,
+                sourceBucket: sourceBucket(refusal.sourceIp)
+            }, 1, at);
+        }
+        catch (err) {
+            this.recordFailures += 1;
+            const message = err instanceof Error ? err.message : String(err);
+            log.error(`[refusals] record failed (refusal still served): ${message}`);
+        }
+    }
+    start() {
+        this.flusher.start();
+    }
+    /** Final flush, then stop. */
+    stop() {
+        return this.flusher.stop();
+    }
+    /** Drain and write now; a sink failure is reported, never thrown. */
+    flush() {
+        return this.flusher.flush();
+    }
+    stats() {
+        return {
+            keys: this.counter.size,
+            overflowed: this.counter.overflowed,
+            recordFailures: this.recordFailures,
+            flusher: this.flusher.stats()
+        };
+    }
+}
+const FUNCTION_NAME = /^[a-z_][a-z0-9_]*\.[a-z_][a-z0-9_]*$/;
+/**
+ * A sink that writes a batch as one `record_refusals(jsonb)` call inside a
+ * transaction carrying the caller's claims. Claims are resolved per flush so a
+ * pool that was unreachable at startup does not leave the recorder wedged.
+ */
+export const createRecordRefusalsSink = (opts) => {
+    const fn = opts.functionName ?? 'constructive_usage_private.record_refusals';
+    if (!FUNCTION_NAME.test(fn)) {
+        throw new Error(`createRecordRefusalsSink: invalid function name ${JSON.stringify(fn)}`);
+    }
+    const [schema, name] = fn.split('.');
+    const sql = `SELECT "${schema}"."${name}"($1::jsonb) AS recorded`;
+    return async (rows) => {
+        if (rows.length === 0)
+            return;
+        const claims = await opts.claims();
+        await withPgClient(opts.pool, claims, async (client) => {
+            await client.query(sql, [JSON.stringify(rows)]);
+        });
+    };
+};

package/esm/usage-counter.js

@@ -0,0 +1,190 @@
+/**
+ * usage-counter — the shared in-memory count + batch-flush mechanism.
+ *
+ * Two classes, neither of which knows what is being counted:
+ *
+ *   - `BoundedCounter<K>` is the map. Consumers pass the key type, how a key
+ *     serialises (`keyOf`) and where a key folds to once the map is full
+ *     (`overflowKey`). `increment` is O(1), synchronous and never throws, so a
+ *     request path can call it while refusing traffic without ever waiting on,
+ *     or being affected by, whatever eventually stores the counts.
+ *   - `CounterFlusher<K>` is the loop. It drains the counter on a jittered
+ *     interval, hands the batch to a `sink`, and owns the failure policy: a
+ *     batch the sink cannot write is reported through `onError` *and dropped*.
+ *     Re-queuing under a broken sink is how a bounded counter becomes an
+ *     unbounded one, and the counter is already accumulating the next window.
+ *
+ * Refusal observability instantiates these with a refusal key and a sink that
+ * calls `constructive_usage_private.record_refusals` (see `refusals.ts`); the
+ * page/request metering lane instantiates the same two classes with its own
+ * `K`, `keyOf`, `overflowKey`, bound, interval and sink. The seam is the
+ * constructor arguments — nothing in this file is specific to either.
+ *
+ * Counters live in process memory only. A crash loses at most one interval's
+ * worth of counts; `stop()` flushes on graceful shutdown. That is deliberate:
+ * the alternative is a durable write per event, which is the thing counting in
+ * memory exists to avoid.
+ *
+ * @module usage-counter
+ */
+export class BoundedCounter {
+    entries = new Map();
+    overflowedSinceDrain = 0;
+    maxKeys;
+    keyOf;
+    overflowKey;
+    constructor(opts) {
+        if (!Number.isInteger(opts.maxKeys) || opts.maxKeys < 1) {
+            throw new Error(`BoundedCounter: maxKeys must be a positive integer, got ${opts.maxKeys}`);
+        }
+        this.maxKeys = opts.maxKeys;
+        this.keyOf = opts.keyOf;
+        this.overflowKey = opts.overflowKey;
+    }
+    /** Distinct keys currently held. */
+    get size() {
+        return this.entries.size;
+    }
+    /** Increments folded into an overflow key since the last drain. */
+    get overflowed() {
+        return this.overflowedSinceDrain;
+    }
+    /**
+     * Add `by` to `key`. Synchronous, O(1), never throws for a well-formed
+     * `keyOf`/`overflowKey`; the caller's request path must not depend on it in
+     * any other way.
+     */
+    increment(key, by = 1, at = Date.now()) {
+        let id = this.keyOf(key);
+        let entry = this.entries.get(id);
+        if (!entry && this.entries.size >= this.maxKeys) {
+            key = this.overflowKey(key);
+            id = this.keyOf(key);
+            entry = this.entries.get(id);
+            this.overflowedSinceDrain += by;
+        }
+        if (!entry) {
+            this.entries.set(id, { key, count: by, firstAt: at, lastAt: at });
+            return;
+        }
+        entry.count += by;
+        if (at < entry.firstAt)
+            entry.firstAt = at;
+        if (at > entry.lastAt)
+            entry.lastAt = at;
+    }
+    /**
+     * Return every entry and start a fresh window. The returned array is the
+     * only reference to those entries, so a slow sink never contends with the
+     * hot path.
+     */
+    drain() {
+        const drained = Array.from(this.entries.values());
+        this.entries.clear();
+        this.overflowedSinceDrain = 0;
+        return drained;
+    }
+}
+export class CounterFlusher {
+    counter;
+    sink;
+    opts;
+    timer = null;
+    inFlight = null;
+    running = false;
+    lastFlushAt = null;
+    lastErrorAt = null;
+    lastError = null;
+    consecutiveFailures = 0;
+    droppedEntries = 0;
+    constructor(counter, sink, opts) {
+        this.counter = counter;
+        this.sink = sink;
+        this.opts = opts;
+        if (!(opts.intervalMs > 0)) {
+            throw new Error(`CounterFlusher: intervalMs must be positive, got ${opts.intervalMs}`);
+        }
+        if (!(opts.jitterMs >= 0)) {
+            throw new Error(`CounterFlusher: jitterMs must be non-negative, got ${opts.jitterMs}`);
+        }
+    }
+    /** Arm the timer. Idempotent. The timer is unref'd so it never pins the process. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.arm();
+    }
+    /** Disarm the timer and flush whatever is pending. Idempotent. */
+    async stop() {
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        await this.flush();
+    }
+    /**
+     * Drain and write now. Never rejects: a sink failure goes to `onError`. If a
+     * flush is already in flight the call waits for it and then runs its own, so
+     * two overlapping timers cannot send batches out of order.
+     */
+    async flush() {
+        if (this.inFlight)
+            await this.inFlight;
+        const run = this.flushOnce();
+        this.inFlight = run;
+        try {
+            await run;
+        }
+        finally {
+            if (this.inFlight === run)
+                this.inFlight = null;
+        }
+    }
+    stats() {
+        return {
+            lastFlushAt: this.lastFlushAt,
+            lastErrorAt: this.lastErrorAt,
+            lastError: this.lastError,
+            consecutiveFailures: this.consecutiveFailures,
+            droppedEntries: this.droppedEntries,
+            running: this.running
+        };
+    }
+    arm() {
+        const delay = this.opts.intervalMs + Math.floor(Math.random() * (this.opts.jitterMs + 1));
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.flush().finally(() => {
+                if (this.running)
+                    this.arm();
+            });
+        }, delay);
+        this.timer.unref?.();
+    }
+    async flushOnce() {
+        const entries = this.counter.drain();
+        if (entries.length === 0)
+            return;
+        try {
+            await this.sink(entries);
+            this.lastFlushAt = Date.now();
+            this.consecutiveFailures = 0;
+        }
+        catch (err) {
+            this.lastErrorAt = Date.now();
+            this.lastError = err instanceof Error ? err.message : String(err);
+            this.consecutiveFailures += 1;
+            this.droppedEntries += entries.length;
+            // The batch is gone whether or not onError itself misbehaves; a
+            // reporter that throws must not turn one lost window into a stuck loop.
+            try {
+                this.opts.onError(err, entries);
+            }
+            catch {
+                // Fire-and-forget by design: the failure is already recorded in stats().
+            }
+        }
+    }
+}

package/index.d.ts

@@ -42,6 +42,12 @@ export { buildPgSettings } from './pg-settings';
 export { withPgClient } from './pg-client';
 export type { NumericProtectionKey, ProtectionBound, RequestProtection, RequestProtectionInput, } from './request-protection';
 export { ASSUMED_PAGE_SIZE, DEFAULT_REQUEST_PROTECTION, INTROSPECTION_BOUND, PROTECTION_BOUNDS, protectionPgSettings, resolveRequestProtection, } from './request-protection';
+export type { AdmissionLease, AdmissionRefusal, AdmissionRequest } from './admission';
+export { clientIpFrom, ConcurrencyLimiter, RateWindow, trustedProxyHops } from './admission';
+export type { RecordRefusalsSinkOptions, Refusal, RefusalKey, RefusalLane, RefusalReason, RefusalRecorderOptions, RefusalRecorderStats, RefusalRow, RefusalSink } from './refusals';
+export { createRecordRefusalsSink, DEFAULT_REFUSAL_FLUSH_INTERVAL_MS, DEFAULT_REFUSAL_FLUSH_JITTER_MS, DEFAULT_REFUSAL_MAX_KEYS, OVERFLOW_ROUTE, OVERFLOW_SOURCE, REFUSAL_REASONS, refusalKeyOf, refusalOverflowKey, RefusalRecorder, refusalRows, sourceBucket, UNKNOWN_SOURCE } from './refusals';
+export type { BoundedCounterOptions, CounterEntry, CounterFlusherOptions, CounterFlusherStats, CounterSink } from './usage-counter';
+export { BoundedCounter, CounterFlusher } from './usage-counter';
 export { requestIdMiddleware } from './request-id';
 export type { ContextMiddlewareOptions } from './context';
 export { buildContext, createContextMiddleware } from './context';

package/index.js

@@ -36,7 +36,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.webauthnLoader = exports.rlsLoader = exports.requireIdentityProvider = exports.requireDatabaseId = exports.requestProtectionLoader = exports.pubkeyLoader = exports.llmLoader = exports.inferenceLogLoader = exports.identityProvidersLoader = exports.databaseSettingsLoader = exports.createModuleLoader = exports.createLoaderRegistry = exports.createDefaultRegistry = exports.corsLoader = exports.computeLoader = exports.billingLoader = exports.authSurfaceLoader = exports.authSettingsLoader = exports.agentChatLoader = exports.createContextMiddleware = exports.buildContext = exports.requestIdMiddleware = exports.resolveRequestProtection = exports.protectionPgSettings = exports.PROTECTION_BOUNDS = exports.INTROSPECTION_BOUND = exports.DEFAULT_REQUEST_PROTECTION = exports.ASSUMED_PAGE_SIZE = exports.withPgClient = exports.buildPgSettings = exports.createBillingClient = void 0;
+exports.webauthnLoader = exports.rlsLoader = exports.requireIdentityProvider = exports.requireDatabaseId = exports.requestProtectionLoader = exports.pubkeyLoader = exports.llmLoader = exports.inferenceLogLoader = exports.identityProvidersLoader = exports.databaseSettingsLoader = exports.createModuleLoader = exports.createLoaderRegistry = exports.createDefaultRegistry = exports.corsLoader = exports.computeLoader = exports.billingLoader = exports.authSurfaceLoader = exports.authSettingsLoader = exports.agentChatLoader = exports.createContextMiddleware = exports.buildContext = exports.requestIdMiddleware = exports.CounterFlusher = exports.BoundedCounter = exports.UNKNOWN_SOURCE = exports.sourceBucket = exports.refusalRows = exports.RefusalRecorder = exports.refusalOverflowKey = exports.refusalKeyOf = exports.REFUSAL_REASONS = exports.OVERFLOW_SOURCE = exports.OVERFLOW_ROUTE = exports.DEFAULT_REFUSAL_MAX_KEYS = exports.DEFAULT_REFUSAL_FLUSH_JITTER_MS = exports.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = exports.createRecordRefusalsSink = exports.trustedProxyHops = exports.RateWindow = exports.ConcurrencyLimiter = exports.clientIpFrom = exports.resolveRequestProtection = exports.protectionPgSettings = exports.PROTECTION_BOUNDS = exports.INTROSPECTION_BOUND = exports.DEFAULT_REQUEST_PROTECTION = exports.ASSUMED_PAGE_SIZE = exports.withPgClient = exports.buildPgSettings = exports.createBillingClient = void 0;
 var billing_client_1 = require("./billing-client");
 Object.defineProperty(exports, "createBillingClient", { enumerable: true, get: function () { return billing_client_1.createBillingClient; } });
 var pg_settings_1 = require("./pg-settings");
@@ -51,6 +51,28 @@ Object.defineProperty(exports, "INTROSPECTION_BOUND", { enumerable: true, get: f
 Object.defineProperty(exports, "PROTECTION_BOUNDS", { enumerable: true, get: function () { return request_protection_1.PROTECTION_BOUNDS; } });
 Object.defineProperty(exports, "protectionPgSettings", { enumerable: true, get: function () { return request_protection_1.protectionPgSettings; } });
 Object.defineProperty(exports, "resolveRequestProtection", { enumerable: true, get: function () { return request_protection_1.resolveRequestProtection; } });
+var admission_1 = require("./admission");
+Object.defineProperty(exports, "clientIpFrom", { enumerable: true, get: function () { return admission_1.clientIpFrom; } });
+Object.defineProperty(exports, "ConcurrencyLimiter", { enumerable: true, get: function () { return admission_1.ConcurrencyLimiter; } });
+Object.defineProperty(exports, "RateWindow", { enumerable: true, get: function () { return admission_1.RateWindow; } });
+Object.defineProperty(exports, "trustedProxyHops", { enumerable: true, get: function () { return admission_1.trustedProxyHops; } });
+var refusals_1 = require("./refusals");
+Object.defineProperty(exports, "createRecordRefusalsSink", { enumerable: true, get: function () { return refusals_1.createRecordRefusalsSink; } });
+Object.defineProperty(exports, "DEFAULT_REFUSAL_FLUSH_INTERVAL_MS", { enumerable: true, get: function () { return refusals_1.DEFAULT_REFUSAL_FLUSH_INTERVAL_MS; } });
+Object.defineProperty(exports, "DEFAULT_REFUSAL_FLUSH_JITTER_MS", { enumerable: true, get: function () { return refusals_1.DEFAULT_REFUSAL_FLUSH_JITTER_MS; } });
+Object.defineProperty(exports, "DEFAULT_REFUSAL_MAX_KEYS", { enumerable: true, get: function () { return refusals_1.DEFAULT_REFUSAL_MAX_KEYS; } });
+Object.defineProperty(exports, "OVERFLOW_ROUTE", { enumerable: true, get: function () { return refusals_1.OVERFLOW_ROUTE; } });
+Object.defineProperty(exports, "OVERFLOW_SOURCE", { enumerable: true, get: function () { return refusals_1.OVERFLOW_SOURCE; } });
+Object.defineProperty(exports, "REFUSAL_REASONS", { enumerable: true, get: function () { return refusals_1.REFUSAL_REASONS; } });
+Object.defineProperty(exports, "refusalKeyOf", { enumerable: true, get: function () { return refusals_1.refusalKeyOf; } });
+Object.defineProperty(exports, "refusalOverflowKey", { enumerable: true, get: function () { return refusals_1.refusalOverflowKey; } });
+Object.defineProperty(exports, "RefusalRecorder", { enumerable: true, get: function () { return refusals_1.RefusalRecorder; } });
+Object.defineProperty(exports, "refusalRows", { enumerable: true, get: function () { return refusals_1.refusalRows; } });
+Object.defineProperty(exports, "sourceBucket", { enumerable: true, get: function () { return refusals_1.sourceBucket; } });
+Object.defineProperty(exports, "UNKNOWN_SOURCE", { enumerable: true, get: function () { return refusals_1.UNKNOWN_SOURCE; } });
+var usage_counter_1 = require("./usage-counter");
+Object.defineProperty(exports, "BoundedCounter", { enumerable: true, get: function () { return usage_counter_1.BoundedCounter; } });
+Object.defineProperty(exports, "CounterFlusher", { enumerable: true, get: function () { return usage_counter_1.CounterFlusher; } });
 // Request ID middleware
 var request_id_1 = require("./request-id");
 Object.defineProperty(exports, "requestIdMiddleware", { enumerable: true, get: function () { return request_id_1.requestIdMiddleware; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/express-context",
-  "version": "0.26.2",
+  "version": "0.28.0",
   "description": "Extractable Express middleware for Constructive tenant context — domain resolution, JWT auth, pgSettings, and withPgClient",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -30,13 +30,13 @@
   },
   "dependencies": {
     "@constructive-io/url-domains": "^2.30.1",
-    "@pgpmjs/env": "^2.43.2",
+    "@pgpmjs/env": "^2.43.4",
     "@pgpmjs/logger": "^2.25.1",
-    "@pgpmjs/server-utils": "^3.27.2",
-    "@pgpmjs/types": "^2.53.0",
+    "@pgpmjs/server-utils": "^3.27.4",
+    "@pgpmjs/types": "^2.53.2",
     "lru-cache": "^11.2.7",
     "pg": "^8.21.0",
-    "pg-cache": "^3.27.2",
+    "pg-cache": "^3.27.4",
     "pg-query-context": "^2.30.1"
   },
   "devDependencies": {
@@ -59,5 +59,5 @@
     "jwt",
     "pgSettings"
   ],
-  "gitHead": "5e0bfead2856d1a062b495d343a43e543343f9b8"
+  "gitHead": "01e073830677c0587bab564b7d575a06b5156f0c"
 }

package/pg-settings.js

@@ -33,6 +33,17 @@ function buildPgSettings(input) {
     if (token?.session_id) {
         settings['jwt.claims.session_id'] = token.session_id;
     }
+    // Session lineage (token exchange chains)
+    if (token?.root_session_id) {
+        settings['jwt.claims.root_session_id'] = token.root_session_id;
+    }
+    if (token?.parent_session_id) {
+        settings['jwt.claims.parent_session_id'] = token.parent_session_id;
+    }
+    // Declared purpose of the credential
+    if (token?.intent) {
+        settings['jwt.claims.intent'] = token.intent;
+    }
     // Principal identity (service accounts / bots)
     if (token?.principal_id) {
         settings['jwt.claims.principal_id'] = token.principal_id;

package/refusals.d.ts

@@ -0,0 +1,154 @@
+/**
+ * refusals — the refusal-observability instantiation of `usage-counter`.
+ *
+ * Every refusal the platform issues (a 429 from admission control, a 413 for an
+ * oversized body, a document-gate rejection, a gateway's route or IP window)
+ * is one `RefusalRecorder.record(...)` call at the point the response is
+ * written. That call is an in-memory increment and nothing else — no promise,
+ * no pool, no allocation beyond the key — so a flood costs a counter bump and
+ * refusing traffic keeps working when the recorder's store is down.
+ *
+ * Counts are keyed by `(minute, database, lane, reason, route, source /24)`,
+ * which is exactly the set of questions the platform table answers: which
+ * tenant, why, on which route, from which network, since when. Raw addresses
+ * are never part of the key; `sourceBucket` truncates to a /24 (v4) or /48
+ * (v6) before anything is counted.
+ *
+ * The flush writes the drained batch as one `record_refusals(jsonb)` call —
+ * one statement per window regardless of how many keys it holds.
+ *
+ * @module refusals
+ */
+import type { Pool } from 'pg';
+import type { CounterEntry, CounterFlusherStats } from './usage-counter';
+/** Which platform surface refused the request. */
+export type RefusalLane = 'graphql' | 'sync' | 'static';
+/**
+ * Why a request was refused. Text in the table rather than an enum, so a new
+ * reason is a code change and not a migration; this union is the one list.
+ */
+export type RefusalReason = 'rate_limited' | 'concurrency_saturated' | 'queue_timeout' | 'request_too_large' | 'query_too_deep' | 'query_too_costly' | 'page_size_too_large' | 'anonymous_not_callable' | 'route_rate_limited';
+export declare const REFUSAL_REASONS: readonly RefusalReason[];
+/** One refused request, as the emitter sees it. */
+export interface Refusal {
+    /** The tenant refused, or null when the request never resolved one. */
+    databaseId: string | null;
+    lane: RefusalLane;
+    reason: RefusalReason;
+    /** `"POST /graphql"`, a route binding id, `host+path` — what the lane keys on. */
+    routeKey: string;
+    /** The client address as the lane resolved it. Bucketed before it is counted. */
+    sourceIp: string | null | undefined;
+    /** Epoch ms; defaults to now. */
+    at?: number;
+}
+/** The aggregation key — one `refusal_log` row per distinct value per window. */
+export interface RefusalKey {
+    /** Epoch ms, truncated to the minute. */
+    minuteBucket: number;
+    databaseId: string | null;
+    lane: RefusalLane;
+    reason: RefusalReason;
+    routeKey: string;
+    sourceBucket: string;
+}
+/** `source_bucket` when the lane could not resolve an address. */
+export declare const UNKNOWN_SOURCE = "unknown";
+/** `source_bucket` / `route_key` of the fold-down entry once the counter is full. */
+export declare const OVERFLOW_SOURCE = "overflow";
+export declare const OVERFLOW_ROUTE = "*";
+/** A row as `constructive_usage_private.record_refusals(jsonb)` reads it. */
+export interface RefusalRow {
+    minute_bucket: string;
+    database_id: string | null;
+    lane: RefusalLane;
+    reason: RefusalReason;
+    route_key: string;
+    source_bucket: string;
+    count: number;
+    first_seen_at: string;
+    last_seen_at: string;
+}
+export type RefusalSink = (rows: RefusalRow[]) => Promise<void>;
+/**
+ * Reduce a client address to a network prefix: `/24` for IPv4, `/48` for IPv6.
+ * Enough to tell "one network hammering an anonymous route" from "the tenant's
+ * own users"; not enough to be a person. Anything unparseable is `unknown`.
+ */
+export declare const sourceBucket: (ip: string | null | undefined) => string;
+export declare const refusalKeyOf: (key: RefusalKey) => string;
+/**
+ * Where a key folds to once the counter is full: same minute, tenant, lane and
+ * reason; route and source collapsed. A source-spraying flood therefore costs
+ * `maxKeys` entries plus one per `(database, lane, reason)`, the tenant/reason
+ * attribution is never lost, and the presence of an `overflow` row is itself
+ * the signal that a spray happened.
+ */
+export declare const refusalOverflowKey: (key: RefusalKey) => RefusalKey;
+/** Shape a drained batch for `record_refusals(jsonb)`. */
+export declare const refusalRows: (entries: CounterEntry<RefusalKey>[]) => RefusalRow[];
+export interface RefusalRecorderOptions {
+    /** Where a drained batch goes. See `createRecordRefusalsSink`. */
+    sink: RefusalSink;
+    /** Base flush interval. Default 10 s. */
+    intervalMs?: number;
+    /** Jitter added to each interval. Default 2 s. */
+    jitterMs?: number;
+    /** Distinct keys held per window before folding. Default 2,000. */
+    maxKeys?: number;
+    /**
+     * Failure reporter. Defaults to an error log naming the SQL error and how
+     * many refusals were dropped; every failed flush is reported.
+     */
+    onError?: (err: unknown, dropped: CounterEntry<RefusalKey>[]) => void;
+}
+export declare const DEFAULT_REFUSAL_FLUSH_INTERVAL_MS = 10000;
+export declare const DEFAULT_REFUSAL_FLUSH_JITTER_MS = 2000;
+export declare const DEFAULT_REFUSAL_MAX_KEYS = 2000;
+export interface RefusalRecorderStats {
+    keys: number;
+    overflowed: number;
+    recordFailures: number;
+    flusher: CounterFlusherStats;
+}
+/**
+ * `BoundedCounter<RefusalKey>` + `CounterFlusher` + a `record_refusals` sink.
+ * Construct one per process, `start()` it, `record()` from every refusal site,
+ * `stop()` on shutdown.
+ */
+export declare class RefusalRecorder {
+    private readonly counter;
+    private readonly flusher;
+    private recordFailures;
+    constructor(opts: RefusalRecorderOptions);
+    /**
+     * Count one refusal. Synchronous and never throws: the request that is
+     * being refused must finish being refused whatever state the recorder is in.
+     */
+    record(refusal: Refusal): void;
+    start(): void;
+    /** Final flush, then stop. */
+    stop(): Promise<void>;
+    /** Drain and write now; a sink failure is reported, never thrown. */
+    flush(): Promise<void>;
+    stats(): RefusalRecorderStats;
+}
+export interface RecordRefusalsSinkOptions {
+    /** The platform database's pool. */
+    pool: Pool;
+    /**
+     * The transaction-local claims the flush runs under, resolved by the caller
+     * (a service principal plus the platform database id). The function raises
+     * if `jwt.claims.user_id` is absent, so a resolver that returns nothing
+     * useful fails loudly at the first flush rather than writing unattributed.
+     */
+    claims: () => Promise<Record<string, string>>;
+    /** Default `constructive_usage_private.record_refusals`. */
+    functionName?: string;
+}
+/**
+ * A sink that writes a batch as one `record_refusals(jsonb)` call inside a
+ * transaction carrying the caller's claims. Claims are resolved per flush so a
+ * pool that was unreachable at startup does not leave the recorder wedged.
+ */
+export declare const createRecordRefusalsSink: (opts: RecordRefusalsSinkOptions) => RefusalSink;