@ultimat3/http 11.3.0 → 13.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,9 @@
 // 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 { Ctx } from '@ultimat3/core';
+import type { HttpConfig, HttpConfigInput } from './config';
+import type { RequestContext } from './context';
 import type { AuthzDecision } from './hooks';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
@@ -46,3 +49,39 @@ 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.
+
+/**
+ * `RequestContext` IS a `Ctx`, so `asCtx` stays a checked widening rather than an assertion.
+ *
+ * `asCtx` already carries this claim at its own call site and this pin is not a duplicate of it:
+ * `asCtx` is a function body, and a future edit answering a failure there with a cast would delete
+ * the enforcement and leave the comment. A pin has nothing to cast.
+ *
+ * The direction that matters is this one and not the reverse — `Ctx extends RequestContext` is
+ * FALSE by design, because core's `Ctx` carries no `requestHeaders`, which is precisely what
+ * `assertInRequest` exists to prove one way at runtime.
+ */
+export type _RequestContextIsACtx = Assert<RequestContext extends Ctx ? true : false>;

package/src/webhook-verify.ts

@@ -0,0 +1,133 @@
+// The inbound half of the framework's webhook mechanism: prove a request was signed by the holder
+// of a shared secret, recently, over the bytes it actually carries. It is a plain function and not
+// a pipeline stage because a receiver is an ordinary `api/` route — the secret is per sender, and
+// only the route knows which one applies.
+//
+// THE FORMAT IS `@ultimat3/core`'s (`webhook-signature.ts`) and is not re-declared here. That
+// module is at the tier both halves can reach: `@ultimat3/jobs` (tier 3) signs a delivery and its
+// boundary forbids this package, and this package (tier 2) may not reach tier 3. What stays here
+// is the POLICY — what counts as fresh, how large a body may be, and which refusal a receiver
+// answers with.
+
+import type { Clock } from '@ultimat3/core';
+import {
+  isCanonicalWebhookField,
+  parseWebhookSignatureHeader,
+  readWithinLimit,
+  systemClock,
+  timingSafeEqual,
+  WEBHOOK_FIELD_MAX,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_TOPIC_HEADER,
+  webhookMac,
+} from '@ultimat3/core';
+import { bodyInvalid, webhookSignatureInvalid, webhookSignatureStale } from './errors';
+
+/**
+ * How far a delivery's timestamp may sit from this clock, either way. Five minutes is the window
+ * every sender in the wild already assumes, and it is a REPLAY BOUND, not a latency allowance: a
+ * captured request stops being usable after it, which is the only thing that keeps an intercepted
+ * delivery from being replayable forever.
+ */
+export const DEFAULT_WEBHOOK_TOLERANCE_MS = 300_000;
+
+/**
+ * Restated rather than read from `HttpConfig.bodyLimitBytes` (same number, `config.ts`): this
+ * function runs inside a route handler with a raw `Request` and no pipeline config in scope, and a
+ * receiver that must hold a 4 MB payload says so here rather than by widening every route's cap.
+ */
+export const DEFAULT_WEBHOOK_BODY_LIMIT = 1_048_576;
+
+export interface WebhookVerifyOptions {
+  /** The shared secret for THIS sender. Never logged, never rendered into a refusal. */
+  readonly secret: string;
+  /** Defaults to `DEFAULT_WEBHOOK_TOLERANCE_MS`. */
+  readonly toleranceMs?: number;
+  /** Defaults to `DEFAULT_WEBHOOK_BODY_LIMIT`. Enforced while the body streams. */
+  readonly maxBytes?: number;
+  /** Defaults to `systemClock`. A window no test can freeze is a window no test pins. */
+  readonly clock?: Clock;
+}
+
+export interface VerifiedWebhook {
+  /**
+   * The sender's id for this event, signed and therefore unforgeable. It is the DEDUPE key: a
+   * delivery replayed inside the tolerance window verifies again by design, and this is what lets
+   * a receiver notice. The seen-set is the app's table — the framework has nowhere to keep one.
+   */
+  readonly eventId: string;
+  /** The sender's routing label. Carried and signed, never interpreted (axiom 8). */
+  readonly topic: string;
+  /**
+   * The exact text the signature covers. Parse THIS, never `request.json()` — the body stream is
+   * spent, and a re-serialisation would not be the bytes that were signed.
+   */
+  readonly body: string;
+  readonly signedAtMs: number;
+}
+
+/**
+ * Prove the request came from the holder of `secret`, inside the tolerance window, over the bytes
+ * it carries — and answer what was signed.
+ *
+ * The order is deliberate: the mac is checked BEFORE the window, so `X_WEBHOOK_SIGNATURE_STALE`
+ * means "authentic and old" and never "unreadable and old". An operator reading it goes to a clock
+ * or a replay, which is what that code is for.
+ */
+export async function verifyWebhookSignature(
+  request: Request,
+  options: WebhookVerifyOptions,
+): Promise<VerifiedWebhook> {
+  const pathname = new URL(request.url).pathname;
+  const signature = parseWebhookSignatureHeader(request.headers.get(WEBHOOK_SIGNATURE_HEADER));
+  if (signature === undefined) {
+    throw webhookSignatureInvalid(
+      pathname,
+      `no readable ${WEBHOOK_SIGNATURE_HEADER} on the request`,
+    );
+  }
+
+  const eventId = request.headers.get(WEBHOOK_ID_HEADER) ?? '';
+  const topic = request.headers.get(WEBHOOK_TOPIC_HEADER) ?? '';
+  if (!isCanonicalWebhookField(eventId) || !isCanonicalWebhookField(topic)) {
+    throw webhookSignatureInvalid(
+      pathname,
+      `${WEBHOOK_ID_HEADER} and ${WEBHOOK_TOPIC_HEADER} must each be 1-${WEBHOOK_FIELD_MAX} characters and carry no ":"`,
+    );
+  }
+
+  const maxBytes = options.maxBytes ?? DEFAULT_WEBHOOK_BODY_LIMIT;
+  // Through core's counting reader, the same one `UltimateRequest.#read` uses: a sender that
+  // announces no length must not be able to make this handler hold an unbounded payload before the
+  // signature it was never going to pass is even computed.
+  const read = await readWithinLimit(request.body, maxBytes);
+  if ('over' in read) {
+    throw bodyInvalid(pathname, [`body is at least ${read.over} bytes, limit is ${maxBytes}`]);
+  }
+
+  // The mac is core's, over the RAW bytes: an HMAC is over a byte stream, so hashing the prefix
+  // and then the body is identical to hashing one string — and it never round-trips a body that is
+  // not valid UTF-8 through a decoder before the mac is taken over it.
+  const expected = webhookMac({
+    secret: options.secret,
+    timestampText: signature.timestampText,
+    eventId,
+    topic,
+    body: read.bytes,
+  });
+  // `timingSafeEqual`, never `===`: this is a mac comparison, and where the two first differ is
+  // exactly what a timing oracle needs to forge one byte at a time.
+  if (!timingSafeEqual(expected, signature.mac)) {
+    throw webhookSignatureInvalid(pathname, 'the signature does not match the body that arrived');
+  }
+
+  const signedAtMs = signature.timestampSeconds * 1_000;
+  const toleranceMs = options.toleranceMs ?? DEFAULT_WEBHOOK_TOLERANCE_MS;
+  const skewMs = Math.abs((options.clock ?? systemClock).now().getTime() - signedAtMs);
+  // Both directions: a sender whose clock runs ahead is the same replay window pointed the other
+  // way, and accepting the future half doubles it.
+  if (skewMs > toleranceMs) throw webhookSignatureStale(pathname, skewMs, toleranceMs);
+
+  return { eventId, topic, body: new TextDecoder().decode(read.bytes), signedAtMs };
+}