Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(control-api): per-class external GFS read budgets
Alfredo Lopez3a8ed542b49e
diff --git a/control-api/package-lock.json b/control-api/package-lock.jsonindex aa041be5d..07501440f 100644--- a/control-api/package-lock.json+++ b/control-api/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-control-api",- "version": "0.1.605",+ "version": "0.1.606","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-control-api",- "version": "0.1.605",+ "version": "0.1.606","dependencies": {"@clerum/display-field": "file:../packages/display-field","@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",diff --git a/control-api/package.json b/control-api/package.jsonindex adeb0d846..0f2f7f103 100644--- a/control-api/package.json+++ b/control-api/package.json@@ -1,6 +1,6 @@{"name": "clerum-control-api",- "version": "0.1.605",+ "version": "0.1.606","description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets","main": "dist/main.js","engines": {diff --git a/control-api/src/config.ts b/control-api/src/config.tsindex 962126f29..9fca7bbeb 100644--- a/control-api/src/config.ts+++ b/control-api/src/config.ts@@ -210,10 +210,14 @@ type Config = {// defense-in-depth ceiling across authenticated non-token GFS traffic; it// is intentionally wider than the per-class/session/actor budgets.externalGfsIpRlPerMin: number- // Read waterfalls have a separate budget from mutations. A Desktop root- // refresh legitimately performs more reads than a mutation burst, while- // mutation/grant/share ceilings remain deliberately narrow.- externalGfsReadRlPerMin: number+ // Each read class has its own budget, sized from its own observed peak; the+ // three mutation classes share one narrower budget. A Desktop root refresh+ // legitimately performs many resource reads, while grants and shares are+ // read only when the Manage dialog opens.+ externalGfsResourceReadRlPerMin: number+ externalGfsProxyReadRlPerMin: number+ externalGfsGrantsReadRlPerMin: number+ externalGfsSharesReadRlPerMin: numberexternalGfsOperationRlPerMin: number// Stateless-agent wake endpoint: per-host wake rate limit + server-side// coalescence window for the wake-annotation projection.@@ -466,9 +470,13 @@ const WORKFLOW_STEP_DEPENDS_ON_MAX_ITEMS_CEILING = 100const WORKFLOW_STEP_ALLOWED_TOOLS_MAX_ITEMS_CEILING = 100// The step mcpServers env can only lower this value; the CRD hard ceiling remains 20.const WORKFLOW_STEP_MCP_SERVERS_MAX_ITEMS_CEILING = 20-// The two actor-keyed external GFS budgets accept an environment override up-// to twice their default; a larger value refuses to boot.-const EXTERNAL_GFS_READ_RL_PER_MIN_CEILING = 960+// The actor-keyed external GFS budgets accept an environment override up to a+// compiled ceiling; a larger value refuses to boot. The two 480 budgets may+// double; the two 120 budgets may reach 480.+const EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN_CEILING = 960+const EXTERNAL_GFS_PROXY_READ_RL_PER_MIN_CEILING = 960+const EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN_CEILING = 480+const EXTERNAL_GFS_SHARES_READ_RL_PER_MIN_CEILING = 480const EXTERNAL_GFS_OPERATION_RL_PER_MIN_CEILING = 180function normalizePem(value: string): string {@@ -1009,20 +1017,50 @@ export const config: Config = {externalGfsTokenUserRlPerMin: 10,externalGfsTokenIpRlPerMin: 600,externalGfsIpRlPerMin: 1_200,- // The two actor-keyed budgets are overridable within a compiled ceiling.- // Each value feeds the pre-resolution session and (class, IP) buckets, the- // resolved per-actor bucket and the express backstops in- // routes/external/gfs.ts. assertExternalGfsBudgetInvariants below refuses a- // combination where operations exceed reads or reads exceed the per-IP+ // The actor-keyed budgets are overridable within a compiled ceiling. Each+ // class's value feeds that class's pre-resolution session and (class, IP)+ // buckets, its resolved per-actor bucket and its express backstop in+ // routes/external/gfs.ts, all through externalGfsClassRlPerMin.+ // assertExternalGfsBudgetInvariants below refuses a combination where+ // mutations exceed a read class or a read class exceeds the per-IP// all-class bucket.//- // Read: one Desktop surface peaks at 58 resource reads/min after PR #702,- // and the 2026-09-18 incident peaked at 133 in a sliding 60 s. 480 covers+ // The four read classes sum to 1200 per calendar minute (480 + 480 + 120 ++ // 120), which equals the all-class pre:ip bucket (1200): one source IP is+ // capped at that value whatever the class mix. With one shared read budget+ // the nominal sum was 1920. No all-read per-actor cap exists; the test+ // suite states the sum instead of a boot invariant.+ //+ // Peaks below are the busiest sliding 60 s of the 30-day funnel log, prod /+ // dev.+ //+ // Resource (resolve, capabilities, upload status, resources, affordances,+ // children): 133 / 85, the prod peak being the 2026-09-18 incident. One+ // Desktop surface peaks at 58 resource reads/min after PR #702. 480 covers// eight surfaces of one user and is 3.6x the incident peak.- externalGfsReadRlPerMin: boundedIntegerFromEnv(- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN',+ externalGfsResourceReadRlPerMin: boundedIntegerFromEnv(+ 'CONTROL_API_EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN',480,- EXTERNAL_GFS_READ_RL_PER_MIN_CEILING+ EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN_CEILING+ ),+ // Proxy read: 12 / 14. 480 rather than 120 because planned per-row+ // thumbnails fan out one proxy read per listed row, as affordances do today.+ externalGfsProxyReadRlPerMin: boundedIntegerFromEnv(+ 'CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN',+ 480,+ EXTERNAL_GFS_PROXY_READ_RL_PER_MIN_CEILING+ ),+ // Grants and shares reads: 4 / 4 and 2 / 4. Both happen only when the+ // Manage dialog opens; 120 is 30x the observed peak.+ externalGfsGrantsReadRlPerMin: boundedIntegerFromEnv(+ 'CONTROL_API_EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN',+ 120,+ EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN_CEILING+ ),+ externalGfsSharesReadRlPerMin: boundedIntegerFromEnv(+ 'CONTROL_API_EXTERNAL_GFS_SHARES_READ_RL_PER_MIN',+ 120,+ EXTERNAL_GFS_SHARES_READ_RL_PER_MIN_CEILING),// Operation: one maximum-size Desktop upload is at least 27 mutations// (ceil(200 MiB / 8 MiB) parts + create + complete, desktop-app@@ -1200,37 +1238,54 @@ export const config: Config = {* corrected value would leave the operator's setting and the running limit* disagreeing.*- * - Operations must not be allowed more freely than reads.- * - The per-actor read budget must not exceed the per-IP all-class bucket in- * front of it; otherwise that bucket caps it under a different key and the- * configured number is never reached.+ * - A mutation class must not be allowed more freely than its read+ * counterpart: resource, grants and shares mutations share one budget,+ * which must not exceed any of the three read budgets. proxy-read has no+ * mutation counterpart.+ * - No read class may exceed the per-IP all-class bucket in front of it;+ * otherwise that bucket caps it under a different key and the configured+ * number is never reached.*- * The per-IP check cannot fire from the environment today: the read ceiling- * (960) is below the compiled per-IP budget (1200). It guards a change to- * either compiled value, and test/config.externalGfsBudgets.test.ts pins the- * relation.+ * The per-IP check cannot fire from the environment today: the largest read+ * ceiling (960) is below the compiled per-IP budget (1200). It guards a change+ * to either compiled value, and test/config.externalGfsBudgets.test.ts pins+ * the relation for every read class.*/export function assertExternalGfsBudgetInvariants(budgets: {- readPerMin: number+ resourceReadPerMin: number+ proxyReadPerMin: number+ grantsReadPerMin: number+ sharesReadPerMin: numberoperationPerMin: numberipPerMin: number}): void {- if (budgets.operationPerMin > budgets.readPerMin) {- throw new Error(- `CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN (${budgets.operationPerMin}) must not ` +- `exceed CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN (${budgets.readPerMin})`- )- }- if (budgets.readPerMin > budgets.ipPerMin) {- throw new Error(- `CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN (${budgets.readPerMin}) must not exceed ` +- `the per-IP external GFS budget externalGfsIpRlPerMin (${budgets.ipPerMin})`- )+ const reads = [+ ['CONTROL_API_EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN', budgets.resourceReadPerMin, true],+ ['CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN', budgets.proxyReadPerMin, false],+ ['CONTROL_API_EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN', budgets.grantsReadPerMin, true],+ ['CONTROL_API_EXTERNAL_GFS_SHARES_READ_RL_PER_MIN', budgets.sharesReadPerMin, true],+ ] as const+ for (const [name, readPerMin, hasMutationCounterpart] of reads) {+ if (hasMutationCounterpart && budgets.operationPerMin > readPerMin) {+ throw new Error(+ `CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN (${budgets.operationPerMin}) must not ` ++ `exceed ${name} (${readPerMin})`+ )+ }+ if (readPerMin > budgets.ipPerMin) {+ throw new Error(+ `${name} (${readPerMin}) must not exceed ` ++ `the per-IP external GFS budget externalGfsIpRlPerMin (${budgets.ipPerMin})`+ )+ }}}assertExternalGfsBudgetInvariants({- readPerMin: config.externalGfsReadRlPerMin,+ resourceReadPerMin: config.externalGfsResourceReadRlPerMin,+ proxyReadPerMin: config.externalGfsProxyReadRlPerMin,+ grantsReadPerMin: config.externalGfsGrantsReadRlPerMin,+ sharesReadPerMin: config.externalGfsSharesReadRlPerMin,operationPerMin: config.externalGfsOperationRlPerMin,ipPerMin: config.externalGfsIpRlPerMin,})diff --git a/control-api/src/middleware/externalGfsRateLimit.ts b/control-api/src/middleware/externalGfsRateLimit.tsindex 0ea758bb1..fa9d5c8c2 100644--- a/control-api/src/middleware/externalGfsRateLimit.ts+++ b/control-api/src/middleware/externalGfsRateLimit.ts@@ -194,13 +194,30 @@ function sourceIpDigest(req: Request): string {return digest(externalGfsSourceIp(req))}-function operationLimit(operationClass: ExternalGfsOperationClass): number {- return operationClass === 'resource' ||- operationClass === 'proxy-read' ||- operationClass === 'grants-read' ||- operationClass === 'shares-read'- ? config.externalGfsReadRlPerMin- : config.externalGfsOperationRlPerMin+/**+ * The per-minute budget of one operation class. The pre-resolution session and+ * (class, IP) buckets, the resolved actor bucket and the class's express+ * backstop in routes/external/gfs.ts all read it here, so one class cannot be+ * metered under two different numbers. The switch is exhaustive: a new class+ * does not compile until it is given a budget.+ */+export function externalGfsClassRlPerMin(+ operationClass: Exclude<ExternalGfsOperationClass, 'token'>+): number {+ switch (operationClass) {+ case 'resource':+ return config.externalGfsResourceReadRlPerMin+ case 'proxy-read':+ return config.externalGfsProxyReadRlPerMin+ case 'grants-read':+ return config.externalGfsGrantsReadRlPerMin+ case 'shares-read':+ return config.externalGfsSharesReadRlPerMin+ case 'resource-mutation':+ case 'grants-mutation':+ case 'shares-mutation':+ return config.externalGfsOperationRlPerMin+ }}function applyRateLimitHeaders(@@ -389,11 +406,11 @@ export function externalGfsPreResolutionRateLimit(: [{key: `gfs-ext:pre:${operation.operationClass}:session:${sessionDigest}`,- maxPerMinute: operationLimit(operation.operationClass),+ maxPerMinute: externalGfsClassRlPerMin(operation.operationClass),},{key: `gfs-ext:pre:${operation.operationClass}:ip:${sourceIpDigest(req)}`,- maxPerMinute: operationLimit(operation.operationClass),+ maxPerMinute: externalGfsClassRlPerMin(operation.operationClass),},{key: `gfs-ext:pre:ip:${sourceIpDigest(req)}`,@@ -428,7 +445,7 @@ export function externalGfsResolvedOperationRateLimit(}const bucket: Bucket = {key: externalGfsResolvedActorBucketKey(operation.operationClass, authority),- maxPerMinute: operationLimit(operation.operationClass),+ maxPerMinute: externalGfsClassRlPerMin(operation.operationClass),}if (await enforceBuckets({diff --git a/control-api/src/routes/external/gfs.ts b/control-api/src/routes/external/gfs.tsindex 71169bca4..d6befdfb5 100644--- a/control-api/src/routes/external/gfs.ts+++ b/control-api/src/routes/external/gfs.ts@@ -28,6 +28,7 @@ import {import { asyncHandler } from '../../http/asyncHandler.js'import {type ExternalGfsOperationClass,+ externalGfsClassRlPerMin,externalGfsPreResolutionRateLimit,externalGfsResolvedActorBucketKey,externalGfsResolvedOperationRateLimit,@@ -411,7 +412,7 @@ export function createExternalGfsRouter(): Router {})const externalGfsResourceRouteRateLimit = rateLimit({windowMs: 60_000,- limit: config.externalGfsReadRlPerMin,+ limit: externalGfsClassRlPerMin('resource'),standardHeaders: 'draft-7',legacyHeaders: false,keyGenerator: resourceRateKey,@@ -419,7 +420,7 @@ export function createExternalGfsRouter(): Router {})const externalGfsProxyReadRouteRateLimit = rateLimit({windowMs: 60_000,- limit: config.externalGfsReadRlPerMin,+ limit: externalGfsClassRlPerMin('proxy-read'),standardHeaders: 'draft-7',legacyHeaders: false,keyGenerator: proxyReadRateKey,@@ -427,7 +428,7 @@ export function createExternalGfsRouter(): Router {})const externalGfsMutationRouteRateLimit = rateLimit({windowMs: 60_000,- limit: config.externalGfsOperationRlPerMin,+ limit: externalGfsClassRlPerMin('resource-mutation'),standardHeaders: 'draft-7',legacyHeaders: false,keyGenerator: resourceMutationRateKey,@@ -435,7 +436,7 @@ export function createExternalGfsRouter(): Router {})const externalGfsGrantsReadRouteRateLimit = rateLimit({windowMs: 60_000,- limit: config.externalGfsReadRlPerMin,+ limit: externalGfsClassRlPerMin('grants-read'),standardHeaders: 'draft-7',legacyHeaders: false,keyGenerator: grantsReadRateKey,@@ -443,7 +444,7 @@ export function createExternalGfsRouter(): Router {})const externalGfsGrantsMutationRouteRateLimit = rateLimit({windowMs: 60_000,- limit: config.externalGfsOperationRlPerMin,+ limit: externalGfsClassRlPerMin('grants-mutation'),standardHeaders: 'draft-7',legacyHeaders: false,keyGenerator: grantsMutationRateKey,@@ -451,7 +452,7 @@ export function createExternalGfsRouter(): Router {})const externalGfsSharesReadRouteRateLimit = rateLimit({windowMs: 60_000,- limit: config.externalGfsReadRlPerMin,+ limit: externalGfsClassRlPerMin('shares-read'),standardHeaders: 'draft-7',legacyHeaders: false,keyGenerator: sharesReadRateKey,@@ -459,7 +460,7 @@ export function createExternalGfsRouter(): Router {})const externalGfsSharesMutationRouteRateLimit = rateLimit({windowMs: 60_000,- limit: config.externalGfsOperationRlPerMin,+ limit: externalGfsClassRlPerMin('shares-mutation'),standardHeaders: 'draft-7',legacyHeaders: false,keyGenerator: sharesMutationRateKey,@@ -485,11 +486,13 @@ export function createExternalGfsRouter(): Router {// ACL listing is still a privileged manage_acl operation, but it must not// consume the smaller mutation budget: opening the Manage dialog performs// several list/refetch reads before one visible grant/share action. Keep- // those reads in the existing bounded GFS read budget and in a distinct- // actor bucket from mutations.+ // those reads in a distinct actor bucket from mutations. GET /grants and+ // GET /shares share this one bucket, so its limit is the sum of the two+ // read budgets; the per-class Postgres buckets and express backstops still+ // cap each route at its own budget.const externalGrantsReadRateLimit = rateLimitMiddleware({bucketType: 'gfs_grants_external_read',- maxPerMinute: config.externalGfsReadRlPerMin,+ maxPerMinute: config.externalGfsGrantsReadRlPerMin + config.externalGfsSharesReadRlPerMin,getBucketKey: req => {const authority = (req as RequestWithExternalGfsAuthority).gfsAuthorityif (authority?.kind === 'linked-admin') {diff --git a/control-api/test/config.externalGfsBudgets.test.ts b/control-api/test/config.externalGfsBudgets.test.tsindex 2ed8f1dd9..f13d73d90 100644--- a/control-api/test/config.externalGfsBudgets.test.ts+++ b/control-api/test/config.externalGfsBudgets.test.ts@@ -2,8 +2,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest'import { readFileSync } from 'node:fs'/**- * Regression guard for the two actor-keyed external GFS budgets- * (config.externalGfsReadRlPerMin, config.externalGfsOperationRlPerMin).+ * Regression guard for the actor-keyed external GFS budgets: one per read+ * class (resource, proxy-read, grants-read, shares-read) and one shared by the+ * three mutation classes (config.externalGfsOperationRlPerMin).** The operation budget is derived from the largest Desktop upload: one part* per preferred part size up to the default product maximum, plus one create@@ -21,11 +22,61 @@ const UPLOAD_LIFECYCLE_CALLS = 2const MAX_UPLOAD_MUTATIONS =Math.ceil(UPLOAD_PRODUCT_MAX_MIB / UPLOAD_PREFERRED_PART_MIB) + UPLOAD_LIFECYCLE_CALLS+// Every read class: its environment variable, config field, default and+// compiled ceiling.+const READ_CLASSES = [+ {+ env: 'CONTROL_API_EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN',+ field: 'externalGfsResourceReadRlPerMin',+ defaultPerMin: 480,+ ceiling: 960,+ hasMutationCounterpart: true,+ },+ {+ env: 'CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN',+ field: 'externalGfsProxyReadRlPerMin',+ defaultPerMin: 480,+ ceiling: 960,+ hasMutationCounterpart: false,+ },+ {+ env: 'CONTROL_API_EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN',+ field: 'externalGfsGrantsReadRlPerMin',+ defaultPerMin: 120,+ ceiling: 480,+ hasMutationCounterpart: true,+ },+ {+ env: 'CONTROL_API_EXTERNAL_GFS_SHARES_READ_RL_PER_MIN',+ field: 'externalGfsSharesReadRlPerMin',+ defaultPerMin: 120,+ ceiling: 480,+ hasMutationCounterpart: true,+ },+] as const+const ENV_KEYS = [- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN',+ ...READ_CLASSES.map(readClass => readClass.env),'CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN',+ // Removed; deleted here so a host that still sets it cannot affect a case.+ 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN',] as const+const DEFAULT_INVARIANT_INPUT = {+ resourceReadPerMin: 480,+ proxyReadPerMin: 480,+ grantsReadPerMin: 120,+ sharesReadPerMin: 120,+ operationPerMin: 90,+ ipPerMin: 1200,+}+const INVARIANT_FIELD = {+ CONTROL_API_EXTERNAL_GFS_RESOURCE_READ_RL_PER_MIN: 'resourceReadPerMin',+ CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN: 'proxyReadPerMin',+ CONTROL_API_EXTERNAL_GFS_GRANTS_READ_RL_PER_MIN: 'grantsReadPerMin',+ CONTROL_API_EXTERNAL_GFS_SHARES_READ_RL_PER_MIN: 'sharesReadPerMin',+} as const+async function loadConfigModuleWith(overrides: Partial<Record<(typeof ENV_KEYS)[number], string>>) {const originalValues = new Map<string, string | undefined>()for (const key of ENV_KEYS) {@@ -85,75 +136,117 @@ describe('external GFS actor budgets', () => {expect(config.externalGfsOperationRlPerMin).toBeGreaterThanOrEqual(MAX_UPLOAD_MUTATIONS)})- it('defaults to 480 reads and 90 operations per minute', async () => {+ it('L12: defaults to 480/480/120/120 reads and 90 operations per minute', async () => {const { config } = await loadConfigModuleWith({})- expect(config.externalGfsReadRlPerMin).toBe(480)+ expect(config.externalGfsResourceReadRlPerMin).toBe(480)+ expect(config.externalGfsProxyReadRlPerMin).toBe(480)+ expect(config.externalGfsGrantsReadRlPerMin).toBe(120)+ expect(config.externalGfsSharesReadRlPerMin).toBe(120)expect(config.externalGfsOperationRlPerMin).toBe(90)})- it('accepts an environment override within the ceiling', async () => {+ it('L12: the four read classes sum to the per-IP all-class bucket', async () => {+ // Documented, not enforced at boot: one source IP is capped at the per-IP+ // bucket whatever the class mix, and with one shared read budget the+ // nominal sum was 1920.+ const { config } = await loadConfigModuleWith({})+ const readSum =+ config.externalGfsResourceReadRlPerMin ++ config.externalGfsProxyReadRlPerMin ++ config.externalGfsGrantsReadRlPerMin ++ config.externalGfsSharesReadRlPerMin+ expect(readSum).toBe(1200)+ expect(readSum).toBe(config.externalGfsIpRlPerMin)+ })++ it('ignores the removed shared read variable', async () => {const { config } = await loadConfigModuleWith({CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '960',+ })+ expect(config.externalGfsResourceReadRlPerMin).toBe(480)+ expect(config.externalGfsProxyReadRlPerMin).toBe(480)+ expect(config.externalGfsGrantsReadRlPerMin).toBe(120)+ expect(config.externalGfsSharesReadRlPerMin).toBe(120)+ })++ it('accepts every class at its ceiling', async () => {+ const { config } = await loadConfigModuleWith({+ ...Object.fromEntries(+ READ_CLASSES.map(readClass => [readClass.env, String(readClass.ceiling)])+ ),CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN: '180',})- expect(config.externalGfsReadRlPerMin).toBe(960)+ for (const readClass of READ_CLASSES) {+ expect(config[readClass.field]).toBe(readClass.ceiling)+ }expect(config.externalGfsOperationRlPerMin).toBe(180)})- it('refuses to boot above either compiled ceiling', async () => {- await expect(- loadConfigModuleWith({ CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '961' })- ).rejects.toThrow(- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN must be an integer between 1 and 960'- )- await expect(- loadConfigModuleWith({ CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN: '181' })- ).rejects.toThrow(- 'CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN must be an integer between 1 and 180'+ it.each([+ ...READ_CLASSES.map(readClass => [readClass.env, readClass.ceiling] as const),+ ['CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN', 180] as const,+ ])('refuses to boot with %s above its ceiling %i', async (env, ceiling) => {+ await expect(loadConfigModuleWith({ [env]: String(ceiling + 1) })).rejects.toThrow(+ `${env} must be an integer between 1 and ${ceiling}`)})- it('refuses to boot when the operation budget exceeds the read budget', async () => {- await expect(- loadConfigModuleWith({- CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '100',- CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN: '180',- })- ).rejects.toThrow(- 'CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN (180) must not exceed ' +- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN (100)'- )- })+ it.each(READ_CLASSES.filter(readClass => readClass.hasMutationCounterpart))(+ 'refuses to boot when the operation budget exceeds $env',+ async readClass => {+ await expect(+ loadConfigModuleWith({+ // 110 exceeds only the class under test: every other read budget+ // keeps its default of 120 or more.+ [readClass.env]: '100',+ CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN: '110',+ })+ ).rejects.toThrow(+ 'CONTROL_API_EXTERNAL_GFS_OPERATION_RL_PER_MIN (110) must not exceed ' ++ `${readClass.env} (100)`+ )+ }+ )- it('L9: the largest read budget the environment can set stays within the per-IP bucket', async () => {- // The per-IP half of assertExternalGfsBudgetInvariants cannot fire from the- // environment today: the read ceiling is below the compiled per-IP budget.- // This pins that relation, so lowering the per-IP budget or raising the- // read ceiling has to be a decision, not a boot failure found in a deploy.+ it('boots with a proxy-read budget below the operation budget: proxy has no mutations', async () => {const { config } = await loadConfigModuleWith({- CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '960',+ CONTROL_API_EXTERNAL_GFS_PROXY_READ_RL_PER_MIN: '10',})- expect(config.externalGfsReadRlPerMin).toBe(960)- expect(config.externalGfsReadRlPerMin).toBeLessThanOrEqual(config.externalGfsIpRlPerMin)- // 960 is the ceiling: one more is refused by the parser, before the invariant.- await expect(- loadConfigModuleWith({ CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN: '961' })- ).rejects.toThrow(- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN must be an integer between 1 and 960'- )+ expect(config.externalGfsProxyReadRlPerMin).toBe(10)+ expect(config.externalGfsOperationRlPerMin).toBe(90)})- it('refuses a read budget above the per-IP budget and accepts it at the boundary', async () => {- const { assertExternalGfsBudgetInvariants } = await loadConfigModuleWith({})- expect(() =>- assertExternalGfsBudgetInvariants({ readPerMin: 1300, operationPerMin: 90, ipPerMin: 1200 })- ).toThrow(- 'CONTROL_API_EXTERNAL_GFS_READ_RL_PER_MIN (1300) must not exceed ' +- 'the per-IP external GFS budget externalGfsIpRlPerMin (1200)'- )- // Liveness witness for the check being `<=`, not `<`: equal values pass.- expect(() =>- assertExternalGfsBudgetInvariants({ readPerMin: 1200, operationPerMin: 90, ipPerMin: 1200 })- ).not.toThrow()- })+ it.each(READ_CLASSES)(+ 'L9: $env at its ceiling stays within the per-IP bucket',+ async readClass => {+ // The per-IP half of assertExternalGfsBudgetInvariants cannot fire from+ // the environment today: every read ceiling is below the compiled per-IP+ // budget. This pins that relation, so lowering the per-IP budget or+ // raising a read ceiling has to be a decision, not a boot failure found+ // in a deploy.+ const { config } = await loadConfigModuleWith({+ [readClass.env]: String(readClass.ceiling),+ })+ expect(config[readClass.field]).toBe(readClass.ceiling)+ expect(config[readClass.field]).toBeLessThanOrEqual(config.externalGfsIpRlPerMin)+ }+ )++ it.each(READ_CLASSES)(+ 'refuses $env above the per-IP budget and accepts it at the boundary',+ async readClass => {+ const { assertExternalGfsBudgetInvariants } = await loadConfigModuleWith({})+ const field = INVARIANT_FIELD[readClass.env]+ expect(() =>+ assertExternalGfsBudgetInvariants({ ...DEFAULT_INVARIANT_INPUT, [field]: 1300 })+ ).toThrow(+ `${readClass.env} (1300) must not exceed ` ++ 'the per-IP external GFS budget externalGfsIpRlPerMin (1200)'+ )+ // Liveness witness for the check being `<=`, not `<`: equal values pass.+ expect(() =>+ assertExternalGfsBudgetInvariants({ ...DEFAULT_INVARIANT_INPUT, [field]: 1200 })+ ).not.toThrow()+ }+ )})diff --git a/control-api/test/middleware.externalGfsRateLimit.test.ts b/control-api/test/middleware.externalGfsRateLimit.test.tsindex eb89e9a50..5aea5dfc2 100644--- a/control-api/test/middleware.externalGfsRateLimit.test.ts+++ b/control-api/test/middleware.externalGfsRateLimit.test.ts@@ -25,7 +25,12 @@ vi.mock('../src/config.js', () => ({externalGfsTokenUserRlPerMin: 10,externalGfsTokenIpRlPerMin: 600,externalGfsIpRlPerMin: 1200,- externalGfsReadRlPerMin: 120,+ // Distinct per class, so a class metered under another class's budget+ // shows up as a wrong number rather than passing by coincidence.+ externalGfsResourceReadRlPerMin: 120,+ externalGfsProxyReadRlPerMin: 60,+ externalGfsGrantsReadRlPerMin: 45,+ externalGfsSharesReadRlPerMin: 35,externalGfsOperationRlPerMin: 30,},}))@@ -323,7 +328,8 @@ describe('external GFS rate boundary', () => {)expect(keys).toContainEqual(expect.stringMatching(/^gfs-ext:pre:proxy-read:ip:[0-9a-f]{64}$/))expect(keys).toContain(`gfs-ext:resolved:proxy-read:actor:linked-admin:${CONTROL_ADMIN_ID}`)- expect(limits.filter(limit => limit === 120).length).toBe(6)+ expect(limits.filter(limit => limit === 120).length).toBe(3)+ expect(limits.filter(limit => limit === 60).length).toBe(3)expect(limits.filter(limit => limit === 1200).length).toBe(2)expect(limits.filter(limit => limit === 30).length).toBe(0)})@@ -359,10 +365,10 @@ describe('external GFS rate boundary', () => {await request(app).post('/external/gfs/shares').set('x-user-session-token', 'session-acl-write')const calls = checkAndIncrement.mock.calls.map(call => [String(call[0]), Number(call[1])])- expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:grants-read:session:/), 120])+ expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:grants-read:session:/), 45])expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:resolved:grants-read:actor:/),- 120,+ 45,])expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:grants-mutation:session:/),@@ -372,10 +378,10 @@ describe('external GFS rate boundary', () => {expect.stringMatching(/^gfs-ext:resolved:grants-mutation:actor:/),30,])- expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:shares-read:session:/), 120])+ expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:shares-read:session:/), 35])expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:resolved:shares-read:actor:/),- 120,+ 35,])expect(calls).toContainEqual([expect.stringMatching(/^gfs-ext:pre:shares-mutation:session:/),@@ -387,6 +393,42 @@ describe('external GFS rate boundary', () => {])})+ it.each([+ ['GET', '/resources', 'resource', 120],+ ['GET', `/proxy/${RESOURCE_ID}`, 'proxy-read', 60],+ ['GET', '/grants', 'grants-read', 45],+ ['GET', '/shares', 'shares-read', 35],+ ['PATCH', `/resources/${RESOURCE_ID}`, 'resource-mutation', 30],+ ['PUT', '/grants', 'grants-mutation', 30],+ ['POST', '/shares', 'shares-mutation', 30],+ ] as const)(+ 'L12: meters %s %s (%s) under its own class budget %i in all three class buckets',+ async (method, path, operationClass, limit) => {+ const { app, handler } = buildApp()++ const response = await request(app)+ [method.toLowerCase() as 'get' | 'patch' | 'put' | 'post'](`/external/gfs${path}`)+ .set('x-user-session-token', `session-${operationClass}`)++ // Witness: the request went through both phases to the handler.+ expect(response.status).toBe(204)+ expect(handler).toHaveBeenCalledTimes(1)+ const calls = checkAndIncrement.mock.calls.map(call => [String(call[0]), Number(call[1])])+ expect(calls).toEqual([+ [+ expect.stringMatching(new RegExp(`^gfs-ext:pre:${operationClass}:session:[0-9a-f]{64}$`)),+ limit,+ ],+ [+ expect.stringMatching(new RegExp(`^gfs-ext:pre:${operationClass}:ip:[0-9a-f]{64}$`)),+ limit,+ ],+ [expect.stringMatching(/^gfs-ext:pre:ip:[0-9a-f]{64}$/), 1200],+ [`gfs-ext:resolved:${operationClass}:actor:linked-admin:${CONTROL_ADMIN_ID}`, limit],+ ])+ }+ )+it('enforces the 1200/min aggregate IP ceiling after the 120/min read buckets', async () => {checkAndIncrement.mockImplementation((key: string, limit: number) => {if (key.startsWith('gfs-ext:pre:ip:')) return denied(1200)diff --git a/control-api/test/routes.externalGfs.test.ts b/control-api/test/routes.externalGfs.test.tsindex d7828df48..ae33b5d52 100644--- a/control-api/test/routes.externalGfs.test.ts+++ b/control-api/test/routes.externalGfs.test.ts@@ -51,7 +51,10 @@ vi.mock('../src/config.js', () => ({externalGfsTokenUserRlPerMin: 10,externalGfsTokenIpRlPerMin: 600,externalGfsIpRlPerMin: 1200,- externalGfsReadRlPerMin: 120,+ externalGfsResourceReadRlPerMin: 120,+ externalGfsProxyReadRlPerMin: 60,+ externalGfsGrantsReadRlPerMin: 45,+ externalGfsSharesReadRlPerMin: 35,externalGfsOperationRlPerMin: 30,},}))@@ -381,13 +384,11 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)expect(mockSignGfsToken).toHaveBeenCalledTimes(10)})- it('uses the dedicated 120/min read route ceiling without widening mutation ceilings', async () => {- const previousReadLimit = (config as { externalGfsReadRlPerMin: number })- .externalGfsReadRlPerMin- const previousOperationLimit = (config as { externalGfsOperationRlPerMin: number })- .externalGfsOperationRlPerMin- ;(config as { externalGfsReadRlPerMin: number }).externalGfsReadRlPerMin = 2- ;(config as { externalGfsOperationRlPerMin: number }).externalGfsOperationRlPerMin = 2+ it('uses the dedicated resource read route ceiling without widening mutation ceilings', async () => {+ const previousReadLimit = config.externalGfsResourceReadRlPerMin+ const previousOperationLimit = config.externalGfsOperationRlPerMin+ config.externalGfsResourceReadRlPerMin = 2+ config.externalGfsOperationRlPerMin = 2try {auth()dbReturning([])@@ -414,17 +415,16 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id).send({ name: 'rename' })expect(mutation.status).not.toBe(429)} finally {- ;(config as { externalGfsReadRlPerMin: number }).externalGfsReadRlPerMin = previousReadLimit- ;(config as { externalGfsOperationRlPerMin: number }).externalGfsOperationRlPerMin =- previousOperationLimit+ config.externalGfsResourceReadRlPerMin = previousReadLimit+ config.externalGfsOperationRlPerMin = previousOperationLimit}})// The three edge-backstop cases below mock every Postgres bucket as allowing// (dbReturning → count 1), so each 429 can only come from an express backstop.it('reports a resource edge-backstop denial on the rate metric and log', async () => {- const previousReadLimit = config.externalGfsReadRlPerMin- config.externalGfsReadRlPerMin = 2+ const previousReadLimit = config.externalGfsResourceReadRlPerMin+ config.externalGfsResourceReadRlPerMin = 2const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})try {auth()@@ -479,7 +479,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)expect((await edgeBackstopDenials()) - allBefore).toBe(1)} finally {warn.mockRestore()- config.externalGfsReadRlPerMin = previousReadLimit+ config.externalGfsResourceReadRlPerMin = previousReadLimit}})@@ -612,8 +612,8 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)})it('L5: a Postgres denial and a backstop denial for one actor log the same hashedKey', async () => {- const previousReadLimit = config.externalGfsReadRlPerMin- config.externalGfsReadRlPerMin = 2+ const previousReadLimit = config.externalGfsResourceReadRlPerMin+ config.externalGfsResourceReadRlPerMin = 2const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})try {auth()@@ -647,13 +647,13 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id))} finally {warn.mockRestore()- config.externalGfsReadRlPerMin = previousReadLimit+ config.externalGfsResourceReadRlPerMin = previousReadLimit}})it('L10: logs the first backstop denial per key and window, and counts every denial', async () => {- const previousReadLimit = config.externalGfsReadRlPerMin- config.externalGfsReadRlPerMin = 2+ const previousReadLimit = config.externalGfsResourceReadRlPerMin+ config.externalGfsResourceReadRlPerMin = 2const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})try {auth()@@ -683,13 +683,13 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)])} finally {warn.mockRestore()- config.externalGfsReadRlPerMin = previousReadLimit+ config.externalGfsResourceReadRlPerMin = previousReadLimit}})it('L22: reports the exact seconds left in the backstop window', async () => {- const previousReadLimit = config.externalGfsReadRlPerMin- config.externalGfsReadRlPerMin = 1+ const previousReadLimit = config.externalGfsResourceReadRlPerMin+ config.externalGfsResourceReadRlPerMin = 1const warn = vi.spyOn(rootLogger, 'warn').mockImplementation(() => {})const windowOpenedAt = Date.now()vi.useFakeTimers({ toFake: ['Date'], now: windowOpenedAt })@@ -712,14 +712,17 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)} finally {vi.useRealTimers()warn.mockRestore()- config.externalGfsReadRlPerMin = previousReadLimit+ config.externalGfsResourceReadRlPerMin = previousReadLimit}})type BudgetKey =| 'externalGfsIngressRlPerMin'| 'externalGfsTokenUserRlPerMin'- | 'externalGfsReadRlPerMin'+ | 'externalGfsResourceReadRlPerMin'+ | 'externalGfsProxyReadRlPerMin'+ | 'externalGfsGrantsReadRlPerMin'+ | 'externalGfsSharesReadRlPerMin'| 'externalGfsOperationRlPerMin'const SOURCE_IP = '203.0.113.9'const actorKey = (operationClass: string) =>@@ -760,7 +763,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)},{guard: 'resource',- budget: 'externalGfsReadRlPerMin',+ budget: 'externalGfsResourceReadRlPerMin',method: 'get',path: '/external/gfs/resources',operationClass: 'resource',@@ -770,7 +773,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)},{guard: 'proxy-read',- budget: 'externalGfsReadRlPerMin',+ budget: 'externalGfsProxyReadRlPerMin',method: 'get',path: `/external/gfs/proxy/${R}`,operationClass: 'proxy-read',@@ -791,7 +794,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)},{guard: 'grants-read',- budget: 'externalGfsReadRlPerMin',+ budget: 'externalGfsGrantsReadRlPerMin',method: 'get',path: `/external/gfs/grants?resourceId=${R}`,operationClass: 'grants-read',@@ -812,7 +815,7 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)},{guard: 'shares-read',- budget: 'externalGfsReadRlPerMin',+ budget: 'externalGfsSharesReadRlPerMin',method: 'get',path: `/external/gfs/shares?resourceId=${R}`,operationClass: 'shares-read',@@ -900,6 +903,43 @@ describe('POST /external/gfs/token (user mint — existing signer, sub=users.id)})+ it.each([+ ['grants', `/external/gfs/grants?resourceId=${R}`],+ ['shares', `/external/gfs/shares?resourceId=${R}`],+ ])(+ 'L12: GET /%s shares one grants/shares read bucket whose limit is the sum of both budgets',+ async (_name, path) => {+ // 45 + 35 in the mocked config: the per-class buckets still cap each+ // route at its own budget, so only the shared bucket carries the sum.+ const sharedLimit =+ config.externalGfsGrantsReadRlPerMin + config.externalGfsSharesReadRlPerMin+ expect(sharedLimit).toBe(80)+ auth()+ let sharedCount = sharedLimit+ const sharedKeys: string[] = []+ dbReturning([], {+ rateLimitCountFor: key => {+ if (!key.startsWith('gfsgrants-ext-read:')) return 1+ sharedKeys.push(key)+ return sharedCount+ },+ })+ const app = await buildApp()+ const send = () => request(app).get(path).set('x-user-session-token', 'sess')++ const atLimit = await send()+ expect(atLimit.status).not.toBe(429)+ expect(atLimit.headers['x-ratelimit-limit']).toBe('80')++ sharedCount = sharedLimit + 1+ const overLimit = await send()+ expect(overLimit.status).toBe(429)+ expect(overLimit.headers['x-ratelimit-limit']).toBe('80')+ // Witness: both requests reached the shared bucket under the one key.+ expect(sharedKeys).toEqual([`gfsgrants-ext-read:user:${U1}`, `gfsgrants-ext-read:user:${U1}`])+ }+ )+it('mints a gfs token for the user with the EXISTING signGfsToken (sub=users.id)', async () => {auth()const app = await buildApp()diff --git a/control-api/test/routes.externalGfsRateLimitStress.realPostgres.integration.test.ts b/control-api/test/routes.externalGfsRateLimitStress.realPostgres.integration.test.tsindex 785d1fce0..1ef3a9b07 100644--- a/control-api/test/routes.externalGfsRateLimitStress.realPostgres.integration.test.ts+++ b/control-api/test/routes.externalGfsRateLimitStress.realPostgres.integration.test.ts@@ -43,6 +43,11 @@ const INGRESS_L = 1_800const IP_L_DEFAULT = 1_200const MINUTE_MS = 60_000+/** Every read class at `read`: for scenarios that exercise one read class. */+function uniformBudgets(read: number, operation: number, ip: number): Budgets {+ return { resource: read, proxy: read, grants: read, shares: read, operation, ip }+}+function databaseUrl(baseUrl: string, database: string): string {const url = new URL(baseUrl)url.pathname = `/${database}`@@ -53,7 +58,14 @@ function quoteIdent(value: string): string {return `"${value.replace(/"/g, '""')}"`}-type Budgets = { read: number; operation: number; ip: number }+type Budgets = {+ resource: number+ proxy: number+ grants: number+ shares: number+ operation: number+ ip: number+}type Sent = {path: stringstatus: number@@ -149,11 +161,17 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg/** Sets a boot-valid budget, clears the ledger, returns a fresh app and the scenario minute. */async function startScenario(budgets: Budgets) {mod.assertExternalGfsBudgetInvariants({- readPerMin: budgets.read,+ resourceReadPerMin: budgets.resource,+ proxyReadPerMin: budgets.proxy,+ grantsReadPerMin: budgets.grants,+ sharesReadPerMin: budgets.shares,operationPerMin: budgets.operation,ipPerMin: budgets.ip,})- mod.config.externalGfsReadRlPerMin = budgets.read+ mod.config.externalGfsResourceReadRlPerMin = budgets.resource+ mod.config.externalGfsProxyReadRlPerMin = budgets.proxy+ mod.config.externalGfsGrantsReadRlPerMin = budgets.grants+ mod.config.externalGfsSharesReadRlPerMin = budgets.sharesmod.config.externalGfsOperationRlPerMin = budgets.operationmod.config.externalGfsIpRlPerMin = budgets.ipawait mod.pool.query('DELETE FROM rate_limit_buckets')@@ -249,8 +267,10 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg/** Limit of every bucket key these scenarios can create; an unknown key fails loudly. */function limitOf(key: string, budgets: Budgets): number {if (key.startsWith('gfs-ext:pre:ip:')) return budgets.ip- if (/^gfs-ext:(pre|resolved):(resource|grants-read):/.test(key)) return budgets.read- if (key.startsWith('gfsgrants-ext-read:user:')) return budgets.read+ if (/^gfs-ext:(pre|resolved):resource:/.test(key)) return budgets.resource+ if (/^gfs-ext:(pre|resolved):grants-read:/.test(key)) return budgets.grants+ // GET /grants and GET /shares share this bucket; its limit is the sum.+ if (key.startsWith('gfsgrants-ext-read:user:')) return budgets.grants + budgets.sharesthrow new Error(`unexpected rate limit bucket in the ledger: ${key}`)}@@ -305,7 +325,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg}it('S1: 20 users with distinct sessions and IPs each get exactly the read budget', async () => {- const budgets = { read: 6, operation: 6, ip: IP_L_DEFAULT }+ const budgets = uniformBudgets(6, 6, IP_L_DEFAULT)const { app } = await startScenario(budgets)const users = await Promise.all(Array.from({ length: 20 }, () => seedUser()))const resourceId = randomUUID()@@ -319,7 +339,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg)))- const labels = run.result.map(response => classify(response, budgets.read))+ const labels = run.result.map(response => classify(response, budgets.resource))expect(run.result).toHaveLength(200)for (let user = 0; user < 20; user += 1) {@@ -348,7 +368,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg}, 120_000)it('S2a: 20 users behind one IP share the (class, IP) read bucket', async () => {- const budgets = { read: 30, operation: 30, ip: IP_L_DEFAULT }+ const budgets = uniformBudgets(30, 30, IP_L_DEFAULT)const { app } = await startScenario(budgets)const users = await Promise.all(Array.from({ length: 20 }, () => seedUser()))const resourceId = randomUUID()@@ -363,7 +383,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg))- expect(tally(run.result.map(response => classify(response, budgets.read)))).toEqual({+ expect(tally(run.result.map(response => classify(response, budgets.resource)))).toEqual({'allowed:200': 30,'postgres:30': 70,})@@ -382,10 +402,12 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postgexpect(run.logged).toEqual(run.metricDelta)}, 120_000)- it('S2b: the per-IP all-class bucket caps two read classes behind one IP', async () => {- // Boot-valid: read (30) <= ip (40). pre:ip can only deny when several- // classes share the IP, because each class alone is capped at read L first.- const budgets = { read: 30, operation: 30, ip: 40 }+ it('S2b: each class bucket and the per-IP all-class bucket cap two read classes behind one IP', async () => {+ // Boot-valid: operation (20) <= every read class with mutations, and every+ // read class <= ip (40). pre:ip can only deny when several classes share+ // the IP, because each class alone is capped at its own L first. The two+ // classes carry different budgets, so each bucket must use its own class's.+ const budgets = { resource: 30, proxy: 30, grants: 20, shares: 20, operation: 20, ip: 40 }const { app } = await startScenario(budgets)const users = await Promise.all(Array.from({ length: 10 }, () => seedUser()))const resourceId = randomUUID()@@ -404,14 +426,23 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg)))- const labels = run.result.map(response => classify(response, budgets.read))+ const labels = run.result.map(response => classify(response, budgets.resource))const tallied = tally(labels)- expect(tallied['postgres:40']).toBe(10)+ // The (grants-read, IP) bucket sees 25 against 20 and denies 5; pre:ip+ // then sees 25 resource + 20 grants = 45 against 40 and denies 5.+ expect(tallied['postgres:20']).toBe(5)+ expect(tallied['postgres:40']).toBe(5)expect((tallied['allowed:200'] ?? 0) + (tallied['allowed:403'] ?? 0)).toBe(40)expect(Object.keys(tallied).sort()).toEqual(- ['allowed:200', 'allowed:403', 'postgres:40'].filter(label => tallied[label] !== undefined)+ ['allowed:200', 'allowed:403', 'postgres:20', 'postgres:40'].filter(+ label => tallied[label] !== undefined+ ))+ // Only the grants class is capped at 20.+ run.result.forEach((response, index) => {+ if (labels[index] === 'postgres:20') expect(response.path).toContain('/grants')+ })// "Allowed" is defined per route: affordances answer 200, the grants list// answers 403 manage_acl_required for a caller without manage_acl.for (const response of run.result) {@@ -426,7 +457,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postgexpect(counts(ledger, 'gfs-ext:pre:grants-read:session:')).toEqual(Array(5).fill(5))expect(counts(ledger, 'gfs-ext:pre:resource:ip:')).toEqual([25])expect(counts(ledger, 'gfs-ext:pre:grants-read:ip:')).toEqual([25])- expect(counts(ledger, 'gfs-ext:pre:ip:')).toEqual([50])+ expect(counts(ledger, 'gfs-ext:pre:ip:')).toEqual([45])expect(sum(counts(ledger, 'gfs-ext:resolved:'))).toBe(40)expect(sum(counts(ledger, 'gfsgrants-ext-read:user:'))).toBe(tallied['allowed:403'] ?? 0)expect(ledgerDenials(ledger, budgets)).toBe(10)@@ -440,7 +471,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg}, 120_000)it('S3: two sessions of one user share the resolved actor bucket', async () => {- const budgets = { read: 10, operation: 10, ip: IP_L_DEFAULT }+ const budgets = uniformBudgets(10, 10, IP_L_DEFAULT)const { app } = await startScenario(budgets)const userId = await seedUser()const resourceId = randomUUID()@@ -456,7 +487,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg]))- expect(tally(run.result.map(response => classify(response, budgets.read)))).toEqual({+ expect(tally(run.result.map(response => classify(response, budgets.resource)))).toEqual({'allowed:200': 10,'postgres:10': 6,})@@ -478,7 +509,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg}, 120_000)it('S4: a burst straddling a minute boundary is denied only by the route backstop', async () => {- const budgets = { read: 8, operation: 8, ip: IP_L_DEFAULT }+ const budgets = uniformBudgets(8, 8, IP_L_DEFAULT)const { app, minuteMs } = await startScenario(budgets)const userId = await seedUser()const resourceId = randomUUID()@@ -491,7 +522,7 @@ describeRealPostgres('external GFS rate limits under concurrent load (real Postg))const labelsOf = (responses: Sent[]) =>- tally(responses.map(response => classify(response, budgets.read)))+ tally(responses.map(response => classify(response, budgets.resource)))// A: 50 s into window 1. Opens the backstop window, fills the Postgres buckets.vi.setSystemTime(minuteMs + 50_000)diff --git a/docs/how-to/codeql-js-missing-rate-limiting.md b/docs/how-to/codeql-js-missing-rate-limiting.mdindex 368bb8640..39864ffeb 100644--- a/docs/how-to/codeql-js-missing-rate-limiting.md+++ b/docs/how-to/codeql-js-missing-rate-limiting.md@@ -26,14 +26,14 @@ may still alert until an `express-rate-limit` **edge backstop** is added (seeTier defaults (requests/minute, per verified admin session identity unless noted):-| Tier | Limit | Config anchor |-| ---------------------------- | -------- | ---------------------------------------------------------- |-| Admin public token | 20 | `adminPublicTokenRlPerMin` |-| Admin workflow grant read | 60 | `workflowGrantReadRateLimit` |-| Admin workflow grant write | 20 | `workflowGrantWriteRateLimit` |-| Registry identity voucher | 30 | inline in `registry.ts` |-| Registry connect request | 3 | inline in `registryConnect.ts` |-| External GFS read / mutation | 120 / 30 | `externalGfsReadRlPerMin` / `externalGfsOperationRlPerMin` |+| Tier | Limit | Config anchor |+| -------------------------------------------------------------- | ----------------------- | ------------------------------ |+| Admin public token | 20 | `adminPublicTokenRlPerMin` |+| Admin workflow grant read | 60 | `workflowGrantReadRateLimit` |+| Admin workflow grant write | 20 | `workflowGrantWriteRateLimit` |+| Registry identity voucher | 30 | inline in `registry.ts` |+| Registry connect request | 3 | inline in `registryConnect.ts` |+| External GFS read (resource, proxy, grants, shares) / mutation | 480, 480, 120, 120 / 90 | `externalGfsClassRlPerMin` |## PR #428 / F4 scope (fixed in branch)