@ultimat3/http 11.3.0 → 12.0.0

package/src/rate-limit-errors.ts

@@ -14,7 +14,7 @@ export const rateLimited = (key: string, retryAfterSeconds: number): HttpError =
   new HttpError({
     code: 'X_RATE_LIMITED',
     cause: `the rate limit for this caller is exhausted; it refills in ${retryAfterSeconds}s`,
-    fix: 'retry after the Retry-After header, or raise rateLimit.buckets in app.config.ts',
+    fix: 'retry after the Retry-After header, or raise the bucket in configureHttp({ rateLimit: { buckets } }) at module scope in a file under apps/*/',
     meta: { key, retryAfterSeconds },
   });
 
@@ -31,7 +31,7 @@ export const rateLimitNotShared = (found: 'process' | 'disabled'): HttpError =>
       found === 'disabled'
         ? "http.rateLimit.scope is 'shared' but http.rateLimit.enabled is false, so the fleet-wide limit is enforced nowhere"
         : "http.rateLimit.scope is 'shared' but the installed store keeps its counters in this process, so each replica would enforce the full bucket on its own",
-    fix: "createServer({ routes, rateLimitStore: postgresRateLimitStore({ executor: { query: (text, values) => db().query({ text, values }) } }) }) — or set http.rateLimit.scope: 'process' in app.config.ts to accept per-replica limits",
+    fix: "createServer({ routes, rateLimitStore: postgresRateLimitStore({ executor: { query: (text, values) => db().query({ text, values }) } }) }) — or defineHttpConfig({ rateLimit: { scope: 'process' } }) to accept per-replica limits",
   });
 
 /**
@@ -56,7 +56,7 @@ const numbers = (bucket: BucketNumbers): string => `${bucket.capacity} / ${bucke
  */
 export const rateLimitBucketConflict = (input: {
   bucket: string;
-  /** `null` when the other declaration is `app.config.ts` rather than a second route. */
+  /** `null` when the other declaration is the app's `configureHttp()` rather than a second route. */
   otherRoute: string | null;
   route: string;
   other: BucketNumbers;
@@ -66,11 +66,11 @@ export const rateLimitBucketConflict = (input: {
     code: 'X_RATE_LIMIT_BUCKET_CONFLICT',
     cause: `bucket "${input.bucket}" has two declarations: ${
       input.otherRoute === null
-        ? 'http.rateLimit.buckets in app.config.ts'
+        ? 'the rateLimit.buckets the app passed to configureHttp()'
         : `route "${input.otherRoute}"`
     } says ${numbers(input.other)}, route "${input.route}" says ${numbers(input.declared)} (capacity / refill per second)${
       input.otherRoute === null
-        ? `; if ${numbers(input.other)} is what this deployment means to enforce, then the route's declaration is the half that is wrong and app.config.ts is not where to say so`
+        ? `; if ${numbers(input.other)} is what this deployment means to enforce, then the route's declaration is the half that is wrong and configureHttp() is not where to say so`
         : ''
     }`,
     // One edit, named. Two joined by "or" leaves the reader to decide which declaration is
@@ -78,7 +78,7 @@ export const rateLimitBucketConflict = (input: {
     // OpenAPI operation publishes, so a config entry duplicating it is the copy that goes stale.
     fix:
       input.otherRoute === null
-        ? `delete http.rateLimit.buckets.${input.bucket} from app.config.ts — the route's declaration is the one the OpenAPI operation publishes, so edit the numbers there if ${numbers(input.declared)} is wrong`
+        ? `delete rateLimit.buckets.${input.bucket} from the app's configureHttp() call — the route's declaration is the one the OpenAPI operation publishes, so edit the numbers there if ${numbers(input.declared)} is wrong`
         : `rename the bucket route "${input.route}" declares — one name is one limit, and "${input.bucket}" is already route "${input.otherRoute}"'s`,
   });
 
@@ -125,7 +125,23 @@ export const rateLimitScopeUnset = (): HttpError =>
     code: 'X_RATE_LIMIT_SCOPE_UNSET',
     cause:
       'http.rateLimit is enabled and the deployment has not declared http.rateLimit.scope, so the numbers below it are per replica rather than per fleet',
-    fix: "in app.config.ts set http.rateLimit.scope: 'process' if this app runs as ONE replica, or 'shared' plus createServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) }) for a fleet-wide limit",
+    fix: "defineHttpConfig({ rateLimit: { scope: 'process' } }) if this app runs as ONE replica, or scope: 'shared' plus createServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) }) for a fleet-wide limit — a process booted by x dev or apps/web/server.ts derives it from the store it installed and never declares it",
+  });
+
+/**
+ * At `defineHttpConfig`, never on the request, and the same shape as every other bucket-name
+ * refusal here: `bucketFor` resolves an unknown name to `default`, so a tenant allowance an author
+ * wrote as 5,000 would silently be the 120-burst read bucket — looser than the declaration, and
+ * visible nowhere. A whole tenant's cap is not a value to discover by watching a graph.
+ */
+export const tenantBucketUnknown = (name: string, declared: readonly string[]): HttpError =>
+  new HttpError({
+    code: 'X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN',
+    cause: `rateLimit.tenantBucket names "${name}" and rateLimit.buckets declares ${
+      declared.length === 0 ? 'no buckets' : declared.join(', ')
+    }`,
+    fix: `add ${name} to the same rateLimit.buckets — configureHttp({ rateLimit: { tenantBucket: '${name}', buckets: { ${name}: { capacity: 5000, refillPerSecond: 100 } } } }) — or drop tenantBucket to leave this app with no per-tenant allowance`,
+    meta: { bucket: name },
   });
 
 /**

package/src/rate-limit.ts

@@ -8,6 +8,7 @@ import {
   rateLimitInvalid,
   rateLimitNotShared,
   rateLimitScopeUnset,
+  tenantBucketUnknown,
 } from './rate-limit-errors';
 
 /**
@@ -42,6 +43,19 @@ export interface RateLimitConfig {
   /** Named buckets; a route selects one via `meta.rateLimit`. `default` is required. */
   readonly buckets: Readonly<Record<string, Bucket>>;
   readonly defaultBucket: string;
+  /**
+   * The bucket a whole TENANT spends, beside — never instead of — the caller's own, or `null` for
+   * an app with no per-tenant allowance.
+   *
+   * `null` by default because no number is defensible without being told: one tenant is a person
+   * and the next is five thousand seats, so a framework-chosen allowance would throttle a real
+   * deployment on the day it installed the framework (axiom 8). It is still the one knob that
+   * answers the failure it exists for — `rateLimitKey` was `actor > org > ip`, EXCLUSIVE, so an
+   * authenticated request never touched an org bucket at all: a tenant with 8,000 seats whose
+   * integration entered a retry loop spent 8,000 per-actor bursts against one shared pool, every
+   * one of them under its own limit, and nothing an operator could set would have refused it.
+   */
+  readonly tenantBucket: string | null;
   /**
    * What this deployment requires of the store. `'shared'` says these numbers are the whole
    * fleet's allowance, and a per-process store then refuses to boot — because N replicas each
@@ -61,6 +75,7 @@ export interface RateLimitConfig {
 export const DEFAULT_RATE_LIMIT: Omit<RateLimitConfig, 'scope'> = {
   enabled: true,
   defaultBucket: 'default',
+  tenantBucket: null,
   buckets: {
     default: { capacity: 120, refillPerSecond: 2 },
     // Login/signup style endpoints: slow, no burst.
@@ -78,6 +93,12 @@ export const resolveRateLimitConfig = (
   input: Partial<RateLimitConfig> | undefined,
 ): RateLimitConfig => {
   const merged = { ...DEFAULT_RATE_LIMIT, ...input };
+  // Here and not at the first request, for `assertRateLimitScope`'s reason: an unknown name falls
+  // through `bucketFor` to `default`, so a tenant allowance somebody wrote as 5,000 would silently
+  // be the 120-burst read bucket — looser than what the author declared, and invisible.
+  if (merged.tenantBucket !== null && !Object.hasOwn(merged.buckets, merged.tenantBucket)) {
+    throw tenantBucketUnknown(merged.tenantBucket, Object.keys(merged.buckets));
+  }
   if (input?.scope !== undefined) return { ...merged, scope: input.scope };
   if (!merged.enabled) return { ...merged, scope: 'process' };
   throw rateLimitScopeUnset();
@@ -275,18 +296,53 @@ export interface RateLimitKeyParts {
 }
 
 /**
- * Key precedence: actor > org > ip. An authenticated actor gets its own bucket so
- * one noisy user cannot exhaust a whole tenant's allowance, and an anonymous
- * request falls back to the connection address.
+ * The namespace the tenant allowance is counted in. Deliberately NOT the route name the caller's
+ * own key carries: a per-route tenant bucket would give one org its whole allowance once per
+ * route, which is not a tenant cap at all — it is the same number multiplied by the route table.
  */
-export const rateLimitKey = (parts: RateLimitKeyParts): string => {
+export const TENANT_SCOPE = 'tenant';
+
+/** One key and the bucket it is spent from. A request spends a LIST of these, never one. */
+export interface RateLimitSpend {
+  readonly key: string;
+  /** A name resolved against `config.rateLimit.buckets` by the limiter, never a `Bucket`. */
+  readonly bucket: string;
+}
+
+/**
+ * Every bucket one request spends, in the order it spends them.
+ *
+ * The CALLER's key first — actor > org > ip, so an authenticated actor gets its own bucket and an
+ * anonymous request falls back to the connection address — and then, when the app declared a
+ * tenant bucket and this caller has an org, that org's own key.
+ *
+ * The second entry is the finding this function was rewritten for. The precedence used to be
+ * EXCLUSIVE: `orgId` was consulted only when `actorId` was null, which `actorView` makes
+ * unreachable for every authenticated request, so no request ever touched an org bucket. A tenant
+ * with 8,000 seats therefore had 8,000 × the per-actor burst against one shared connection pool,
+ * with every individual bucket comfortably inside its limit.
+ *
+ * The caller's key is spent FIRST so a single hostile actor is refused by its own allowance before
+ * it can spend its tenant's — and, because the stage stops at the first refusal, a throttled
+ * caller costs the tenant nothing.
+ */
+export const rateLimitSpends = (
+  parts: RateLimitKeyParts,
+  buckets: { readonly route: string; readonly tenant: string | null },
+): readonly RateLimitSpend[] => {
   const subject =
     parts.actorId !== null
       ? `actor:${parts.actorId}`
       : parts.orgId !== null
         ? `org:${parts.orgId}`
         : `ip:${parts.ip ?? 'unknown'}`;
-  return `${parts.routeName}|${subject}`;
+  const spends: RateLimitSpend[] = [
+    { key: `${parts.routeName}|${subject}`, bucket: buckets.route },
+  ];
+  if (buckets.tenant !== null && parts.orgId !== null) {
+    spends.push({ key: `${TENANT_SCOPE}|org:${parts.orgId}`, bucket: buckets.tenant });
+  }
+  return spends;
 };
 
 export interface RateLimiter {

package/src/response.ts

@@ -1,7 +1,7 @@
 // Response constructors. Every response in the framework is built here so that
 // content types, charsets and cache semantics are decided once instead of per route.
 import { TIMEZONE_HEADER } from '@ultimat3/time';
-import { toProblem } from './error-map';
+import { toProblem } from './error-facts';
 
 type HeaderSource = { readonly headers?: HeadersInit | undefined } | undefined;
 

package/src/stages.ts

@@ -19,7 +19,7 @@ import { type HttpConfig, stripBasePath } from './config';
 import { actorView, elapsedMs, type RequestContext } from './context';
 import { corsHeaders, preflight } from './cors';
 import { checkCsrf, selfOrigin } from './csrf';
-import { factsOf, retryAfterOf } from './error-map';
+import { factsOf, retryAfterOf } from './error-facts';
 import { errorPageResponse } from './error-page';
 import {
   bodyInvalid,
@@ -37,7 +37,7 @@ import { acceptsHtml } from './html-render';
 import { readCookie } from './locale';
 import { compose, type Middleware } from './middleware';
 import { overlayResponse } from './overlay';
-import { type RateLimiter, rateLimitKey } from './rate-limit';
+import { type RateLimitDecision, type RateLimiter, rateLimitSpends } from './rate-limit';
 import { rateLimited } from './rate-limit-errors';
 import type { UltimateRequest } from './request';
 import { addVary, applyCacheHeaders, problem, redirect, SHARED_CACHE_VARY } from './response';
@@ -211,23 +211,45 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
     'rate-limit': async (_request, ctx) => {
       if (!config.rateLimit.enabled) return undefined;
       const actor = actorView(ctx.actor);
-      const key = rateLimitKey({
-        actorId: actor?.id ?? null,
-        orgId: actor?.orgId ?? null,
-        ip: ctx.ip,
-        routeName: ctx.route?.meta.name ?? UNMATCHED_ROUTE,
-      });
-      const decision = await limiter.check(
-        key,
-        ctx.route?.meta.rateLimit ?? config.rateLimit.defaultBucket,
+      // A LIST, and the second entry is why: the key builder used to pick ONE subject —
+      // actor > org > ip, exclusive — so an authenticated request never touched a tenant bucket
+      // and one org's 8,000 seats each ran their own allowance against one shared pool.
+      const spends = rateLimitSpends(
+        {
+          actorId: actor?.id ?? null,
+          orgId: actor?.orgId ?? null,
+          ip: ctx.ip,
+          routeName: ctx.route?.meta.name ?? UNMATCHED_ROUTE,
+        },
+        {
+          route: ctx.route?.meta.rateLimit ?? config.rateLimit.defaultBucket,
+          tenant: config.rateLimit.tenantBucket,
+        },
       );
+      let answer: RateLimitDecision | undefined;
+      let refusedKey: string | undefined;
+      for (const spend of spends) {
+        const decision = await limiter.check(spend.key, spend.bucket);
+        // The bucket closest to refusing is the one the caller has to plan against: reporting
+        // `remaining: 99` off a per-actor bucket while the tenant's holds 2 is a number that
+        // tells a client it may proceed and then refuses its next call.
+        if (answer === undefined || decision.remaining < answer.remaining) answer = decision;
+        if (!decision.allowed) {
+          // The first refusal ends the spend, so a caller its own bucket already refused costs
+          // its tenant nothing — one noisy actor may not drain the allowance it shares.
+          answer = decision;
+          refusedKey = spend.key;
+          break;
+        }
+      }
+      if (answer === undefined) return undefined;
       // Recorded before the throw so the 429 can carry Retry-After and the
       // RateLimit-* headers rather than making the client guess.
-      ctx.rateLimit = decision;
-      for (const [name, value] of Object.entries(limiter.headers(decision))) {
+      ctx.rateLimit = answer;
+      for (const [name, value] of Object.entries(limiter.headers(answer))) {
         ctx.headers.set(name, value);
       }
-      if (!decision.allowed) throw rateLimited(key, decision.retryAfterSeconds);
+      if (refusedKey !== undefined) throw rateLimited(refusedKey, answer.retryAfterSeconds);
       return undefined;
     },
 

package/src/type-pins.ts

@@ -3,6 +3,7 @@
 // test file and a claim written there can never fail. Nothing here emits or is imported — a
 // regression is a build error, the only enforcement that counts (axiom 3).
 
+import type { HttpConfig, HttpConfigInput } from './config';
 import type { AuthzDecision } from './hooks';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
@@ -46,3 +47,26 @@ export type _AuthzDenyNeedsAReason = Assert<
 export type _AuthzDenyCodeIsOptional = Assert<
   { allowed: false; reason: string } extends AuthzDecision ? true : false
 >;
+
+/**
+ * Every key of the RESOLVED config is settable on the input, so nothing this package tunes is
+ * reachable only by editing this package.
+ *
+ * The whole HTTP tuning surface was unreachable from a shipped app until 12.0.0 — one fixed
+ * literal in `@ultimat3/cli` was its only construction — and the half of that defect a rule can
+ * see is this one: a key added to `HttpConfig` and forgotten on `HttpConfigInput` has a default
+ * nobody can override, silently, forever. `scripts/config-readers.ts` cannot see it either: that
+ * ratchet walks `AppConfig` and asks whether a key is READ, and this is the mirror question — can
+ * a key be WRITTEN. A build error naming the key beats both.
+ */
+type UnsettableHttpKey = Exclude<keyof HttpConfig, keyof HttpConfigInput>;
+
+export type _EveryHttpConfigKeyIsSettable = Assert<
+  [UnsettableHttpKey] extends [never] ? true : false
+>;
+
+// There is deliberately NO second pin claiming "every settable key is app-declarable or
+// boot-owned". `AppHttpConfig` is `Omit<HttpConfigInput, BootOwnedHttpKey>`, so that union is
+// `keyof HttpConfigInput` by construction and the assertion is vacuously true whatever anyone
+// edits — a claim that cannot fail is not a claim. The derivation IS the enforcement there; this
+// file only pins what a derivation cannot say.