@ultimat3/http 11.3.0 → 13.0.0

package/src/error-map.ts

@@ -1,8 +1,8 @@
 // The one place a framework error code becomes an HTTP status. A table, not a
 // switch chain: adding a code elsewhere in the framework means adding a row here,
 // and a missing row is a loud 500 rather than a silently wrong 200.
-import { ERROR_DOCS_URL, renderCauseValue, singleLine, stringField } from '@ultimat3/core';
-import { errorStatusInvalid, HTTP_ERROR_TITLES } from './errors';
+// Rendering a throwable for a reader is `error-facts.ts`; this file answers only the status.
+import { errorStatusInvalid } from './errors';
 
 /**
  * code -> status. Codes owned by other packages are listed here on purpose: HTTP
@@ -48,8 +48,10 @@ export const ERROR_STATUS = {
   X_RATE_LIMIT_BUCKET_CONFLICT: 500,
   // Construction time as well: the limiter installed cannot enforce a bucket a route declares.
   X_RATE_LIMIT_BUCKET_UNBOUND: 500,
-  // `defineHttpConfig` time, both of them: a declaration the deployment owes and did not make.
+  // `defineHttpConfig` time, all three: a declaration the deployment owes and did not make, or
+  // made against a bucket nothing declares.
   X_RATE_LIMIT_SCOPE_UNSET: 500,
+  X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN: 500,
   X_TRUST_PROXY_UNSET: 500,
   // Raised by `toBucket` while a route or an action is being projected, never on the request.
   X_RATE_LIMIT_INVALID: 500,
@@ -67,6 +69,15 @@ export const ERROR_STATUS = {
   // 403 and never 401: the caller IS authenticated — that is what makes the forged write work —
   // so a 401 would send a signed-in user to a sign-in page they are already past.
   X_CSRF_BLOCKED: 403,
+  // 401 for both, and never 400: an inbound webhook is well formed and carries a CREDENTIAL — a
+  // timestamped hmac over its own bytes — so what failed is authentication, not the request. Never
+  // 403 either, which means an authenticated caller was refused, and there is no authenticated
+  // caller here. Two codes rather than one because the repairs differ and a sender's dashboard
+  // shows the status: `INVALID` is the wrong secret or a rewritten body, `STALE` is a skewed clock
+  // or a delivery being replayed off a capture. Neither triggers `signInRedirect`, which keys on
+  // `X_UNAUTHENTICATED` alone — a webhook sender is not a browser and has no session to go get.
+  X_WEBHOOK_SIGNATURE_INVALID: 401,
+  X_WEBHOOK_SIGNATURE_STALE: 401,
   // @ultimat3/action — the code every primitive throws when the CALLER's input fails the schema
   // the primitive declared. 400 because that is what the published OpenAPI operation promises for
   // it, and because a missing row made a typo'd uuid a 500: the caller was told the server broke,
@@ -138,6 +149,46 @@ export const ERROR_STATUS = {
   // signed-in caller to a sign-in page that cannot give them a tenant.
   X_TENANCY_ACTOR_ORG_REQUIRED: 403,
   X_TENANCY_CROSS_DENIED: 403,
+  // The three aggregate refusals, all 500 and all deliberately NOT a 4xx, for the reason
+  // `X_QUERY_NOT_PAGEABLE` below is one: nothing the caller sends changes the answer, and the fix
+  // is an edit to the read itself. They earn ROWS rather than a pin in `scripts/error-map-backlog.ts`
+  // because each carries an instruction the app's author needs and an unmapped 5xx is blanked —
+  // `toProblem` replaces an undeclared code's cause with `INTERNAL_CAUSE`, so pinning them would
+  // answer "the server failed while handling this request" for a fault whose own `fix:` names the
+  // exact call to write instead. A row costs no extra page: `stages.ts` reports every `status >= 500`
+  // either way.
+  //
+  // Reached with a request waiting, all three, which is why they are not in the backlog's entity
+  // group ("misuse a handler's author makes") — the mixed-currency and the ±2^53 refusals are
+  // decided by the ROWS, so a read that answered for two years starts failing on the day the data
+  // crosses the line, and `approximateCount()` on a chain whose predicates came from the caller's
+  // own optional filters is one query string away.
+  X_AGGREGATE_UNSUPPORTED: 500,
+  X_AGGREGATE_MIXED_CURRENCY: 500,
+  X_APPROXIMATE_COUNT_FILTERED: 500,
+  // The two search refusals, 500 for the reason the three above are: nothing the caller sends
+  // changes either answer. An entity with no searchable column needs a `searchable()` on one, and
+  // a driver that cannot answer a full-text match needs the Postgres one — both are edits to the
+  // app, and both carry a `fix:` that an unmapped 5xx would blank (`toProblem` replaces an
+  // undeclared code's cause with `INTERNAL_CAUSE`).
+  X_SEARCH_UNDECLARED: 500,
+  X_SEARCH_IN_MEMORY: 500,
+  // The three state-machine refusals, and they are deliberately THREE statuses rather than one:
+  // the machine says the transition does not exist, the row says it is somewhere else, or the
+  // column says there is no machine at all — three different readers and three different repairs.
+  //
+  // 422 and not 400: the request is well formed and its schema passed. The transition the caller
+  // named is not one this machine has, which is the same shape as `X_INVARIANT_VIOLATED` above and
+  // takes its status. Refused before any statement opens a connection, so nothing was written.
+  X_STATE_TRANSITION_ILLEGAL: 422,
+  // 409, the lost update caught. The row moved between the read the caller decided on and the
+  // write it asked for — nothing is wrong with either, and the repair is re-read and retry, which
+  // is precisely what a 409 tells a client to do. A 422 would say "your request is unusable",
+  // which is false: the identical request succeeds a moment later.
+  X_STATE_CONFLICT: 409,
+  // 500, the same shelf as `X_SEARCH_UNDECLARED`: a column with no machine is a declaration the
+  // app has not written, and no request changes that.
+  X_STATE_UNDECLARED: 500,
   // @ultimat3/db — the constraints a request trips, both 409. db's own `fix:` for the unique
   // violation says "answer 409, which is what a raced signup is", and `X_ENTITY_DUPLICATE` — the
   // same event one layer up — is 409 above; a foreign key rides with it because both halves of it
@@ -157,6 +208,46 @@ export const ERROR_STATUS = {
   // it either — the row exists for the reason `X_CORS_CONFIG_INVALID`'s does: this table is the
   // closed one, and a code with no row is a 500 anyway.
   X_ACTION_JOB_UNBRIDGED: 500,
+  // Every `X_WEBHOOK_*` below is OUTBOUND and is thrown inside a worker: `ROLE=worker` opens no
+  // HTTP port, so none of them ever answers a request. The rows exist for the reason
+  // `X_ACTION_JOB_UNBRIDGED`'s does — this table is the closed one, and a code with no row is a
+  // 500 anyway. The INBOUND pair (`X_WEBHOOK_SIGNATURE_*`, 401) is @ultimat3/http's and sits with
+  // the rest of this package's codes above; these are the ones a delivery ends on.
+  X_WEBHOOK_ENDPOINT_UNKNOWN: 500,
+  X_WEBHOOK_ENDPOINT_INVALID: 500,
+  X_WEBHOOK_ENDPOINT_DISABLED: 500,
+  X_WEBHOOK_EVENT_UNKNOWN: 500,
+  X_WEBHOOK_EVENT_INVALID: 500,
+  X_WEBHOOK_DELIVERY_FAILED: 500,
+  X_WEBHOOK_DELIVERY_THROTTLED: 500,
+  X_WEBHOOK_DELIVERY_REJECTED: 500,
+  // Same class again: an export pass runs in a worker, and both codes refuse the DECLARATION —
+  // a `row()` that answers columns nobody declared, and a page too big to hold. Neither is
+  // anything a caller sent.
+  X_EXPORT_ROW_INVALID: 500,
+  X_EXPORT_PART_TOO_LARGE: 500,
+  // @ultimat3/notify — five 500s and one 502, and the split is who failed.
+  //
+  // The five are the app's own declaration: a notifier with no channels, one channel named twice,
+  // a digest window on a bulk channel, a store nothing installed, and a fan-out past the per-run
+  // ceiling. Every `fix:` on those five names a code edit or a boot call, so nothing a caller
+  // sends changes any of them — `X_NOTIFY_FANOUT_TOO_WIDE` is the only one a request can even
+  // INFLUENCE (an action that notifies a whole org), and the repair is still `bulkChannel()` or a
+  // paged `backfill()`, never the request.
+  X_NOTIFY_CHANNELS_EMPTY: 500,
+  X_NOTIFY_CHANNEL_DUPLICATE: 500,
+  X_NOTIFY_FANOUT_TOO_WIDE: 500,
+  X_NOTIFY_STORE_MISSING: 500,
+  X_NOTIFY_DIGEST_UNSUPPORTED: 500,
+  // 502, and it is the one row on this table that answers for somebody else's server. This code
+  // WRAPS a provider rejection — `NotifyDeliveryFailedError` takes the caught value and renders it
+  // — so the thing that failed is the channel's upstream, not this process. It is thrown inside a
+  // job step today (`x jobs show <notifier> --json` is its own `fix:`), so nothing reaches a
+  // request and the number is unobservable either way; the row is chosen for the day that stops
+  // being true, and the asymmetry decides it. A wrong 502 costs nothing. A wrong 500 pages the
+  // on-call for an email provider's outage, because `stages.ts` reports every `status >= 500` to
+  // the error monitor — which is the failure this whole table exists to stop.
+  X_NOTIFY_DELIVERY_FAILED: 502,
   // @ultimat3/policy
   X_POLICY_MISSING: 500,
   X_PERMISSION_UNKNOWN: 500,
@@ -210,12 +301,36 @@ export const ERROR_STATUS = {
   // 404, deliberately NOT 403: the org check fires before anything is read, so answering
   // "forbidden" would confirm that a key exists to the one caller who must not learn it.
   X_STORAGE_ORG_MISMATCH: 404,
+  // @ultimat3/ui — a form control whose `name` is not a usable field path. The owning slice argued
+  // for NO ROW, on the grounds that this is a render-time developer error that can never reach
+  // HTTP, and the argument is right about the code and wrong about the table.
+  //
+  // `scripts/error-map-backlog.ts` is the only "no row" this table has, and its own header says
+  // what an entry there means: "NOT a claim that the code can never cross HTTP … a claim that
+  // nobody has decided yet", with the ratchet promising only that the undecided set never grows.
+  // This code HAS been decided, so a pin would record the opposite of what is known and grow the
+  // one list that may not grow.
+  //
+  // So it takes the answer every other decided-and-unreachable code takes — `X_CORS_CONFIG_INVALID`,
+  // `X_ACTION_JOB_UNBRIDGED`, `X_RATE_LIMIT_NOT_SHARED`. The row is NOT a claim that it reaches a
+  // request. A code with no row already answers 500 (`DEFAULT_STATUS`); the row changes nothing at
+  // runtime and makes that answer a reviewed one instead of an accident, which is the whole reason
+  // this table is closed.
+  X_UI_FORM_PATH_INVALID: 500,
   // @ultimat3/mail
   // The deployment configured no transport. It reaches a caller only through an inline
   // `send(…, { sync: true })` inside a request; the queued path dead-letters instead. A server-side
   // configuration fault either way, so 500 and never a 4xx — nothing the caller sent is wrong, and
   // this is exactly the condition somebody should be paged for.
   X_MAIL_CREDENTIAL_MISSING: 500,
+  // @ultimat3/mcp — the one MCP code that is answered on a REQUEST rather than inside a JSON-RPC
+  // envelope, which is what the rest of that package's backlog group says about the others: the
+  // transport refused before dispatch, so there is no call to answer. 429 because
+  // `mcpHttpRoute` already builds that response by hand (`transport-http.ts`'s `throttled`), with
+  // `retry-after` beside it. The row is what keeps the two surfaces from disagreeing the day the
+  // MCP host is mounted inside this pipeline — a code that renders 429 on one and 500 on the other
+  // is exactly the split this table exists to prevent.
+  X_MCP_RATE_LIMITED: 429,
   // @ultimat3/core
   // The caller asked for a format the pipeline cannot produce (`?f=avif`): the request names an
   // unsupported representation, which is 415 — not a 500, which would blame the server for it.
@@ -303,197 +418,19 @@ export const registerErrorStatus = (statuses: Readonly<Record<string, number>>):
 /** Test seam. Production registers once at boot and never unregisters. */
 export const resetErrorStatus = (): void => APP_ERROR_STATUS.clear();
 
-// Framework table first: `registerErrorStatus` already refuses those codes, so the order is
-// belt-and-braces — but it is the belt that makes "the framework's statuses are fixed" true
-// even if a future caller reaches the map some other way.
-// `APP_ERROR_STATUS` is a `Map`, which is why its half never had `frameworkStatus`'s defect —
-// prefer one for anything keyed by a value a caller chose.
-export const statusFor = (code: string): number =>
-  frameworkStatus(code) ?? APP_ERROR_STATUS.get(code) ?? DEFAULT_STATUS;
-
-/** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
-export interface ErrorFacts {
-  readonly code: string;
-  readonly title: string;
-  readonly cause: string;
-  readonly fix: string;
-  readonly docs: string;
-  readonly status: number;
-  /** Present only when the process is in dev mode; never sent to a client in prod. */
-  readonly stack: string | undefined;
-}
-
-/**
- * One string field off the throwable, through core's `stringField`. The read is a getter call —
- * or a `Proxy`'s `get` trap — on a value the framework did not build, and it throws in the one
- * place with nothing left to answer with: `factsOf` is called by the RECOVER stage, and again by
- * the `problem()` that `recoverWith` degrades to, so a value that refuses to be read took both
- * renderings and `handle()` rejected against its own contract.
- */
-const str = (source: unknown, key: string): string | undefined => {
-  const value = stringField(source, key);
-  return value !== undefined && value.length > 0 ? value : undefined;
-};
-
-/**
- * Normalises any throwable into the framework's error contract. Non-Ultimate
- * throwables still get a code and a fix, because "errors are instructions" has to
- * hold for the accidental `TypeError` too.
- */
-export const factsOf = (error: unknown): ErrorFacts => {
-  const code = str(error, 'code') ?? 'X_INTERNAL';
-  // The error's own title first: every `UltimateError` resolves one from the code registry at
-  // construction, so this renders the OWNING package's title — including the codes http only
-  // borrows (`X_FORBIDDEN` is policy's, `X_UNAUTHENTICATED` is auth's) and so cannot title itself.
-  // Falling through to `message` here shipped the code twice: `X_FORBIDDEN: policy denied… — …`.
-  const title =
-    str(error, 'title') ??
-    // `Object.hasOwn` for `statusFor`'s reason, one table over: `code: 'toString'` read the
-    // function off the prototype and put it in `title`, which is rendered into the problem
-    // document and the terminal.
-    (Object.hasOwn(HTTP_ERROR_TITLES, code)
-      ? HTTP_ERROR_TITLES[code as keyof typeof HTTP_ERROR_TITLES]
-      : undefined) ??
-    str(error, 'message') ??
-    'unhandled server error';
-  // The last fallback is the only one that touches the throwable whole, and every throwable a
-  // request produces reaches it. `String()` runs the value's own `toString`, so the value that
-  // took the request down took the 500 renderer with it and the server had nothing left to send.
-  const cause = str(error, 'cause') ?? str(error, 'message') ?? renderCauseValue(error);
-  return {
-    code,
-    title,
-    cause,
-    // `x logs tail` is in `PLANNED_COMMANDS` — it exits `X_NOT_IMPLEMENTED`. A fix line naming a
-    // command that throws is axiom 4 inverted: the one instruction the reader is given fails.
-    // `x errors explain` ships, and it is the command that answers "what is this code".
-    fix: str(error, 'fix') ?? `x errors explain ${code} --json   # then fix the throwing call site`,
-    // Core's one constant, never a per-code URL: `wiki/` is the only public documentation surface
-    // and a code lives there in a table row, which has no anchor. An `UltimateError` already
-    // resolved this at construction, so the fallback only fires for a throwable the framework did
-    // not build — and it must not be the `https://ultimate.dev/errors/<code>` link that answered
-    // 404 on every problem document this package has ever rendered.
-    docs: str(error, 'docs') ?? ERROR_DOCS_URL,
-    status: statusFor(code),
-    stack: str(error, 'stack'),
-  };
-};
-
-/**
- * `Retry-After`, in whole seconds, for a refusal that computed one — or `undefined`.
- *
- * The contract it reads is already written down by the packages BELOW this one: `@ultimat3/auth`'s
- * `kdfOverloaded` says "`retryAfterSeconds` rides in `meta` because this package cannot reach an
- * HTTP header; the host reads it onto `Retry-After`", and `rateLimited` in this package carries the
- * same field. Nothing was the host. So a 503 shed by the KDF gate and a 429 from an account lockout
- * both told the caller to come back and never said when — which is the shed-with-no-delay pattern
- * the `admit` stage exists to avoid, one layer in.
- *
- * Total, for `str`'s reason one function up: `meta` is a property read on a value this package did
- * not build, and it is read in the frame that decides what the caller sees.
- */
-export function retryAfterOf(error: unknown): number | undefined {
-  if (typeof error !== 'object' || error === null) return undefined;
-  try {
-    const meta: unknown = (error as Record<string, unknown>)['meta'];
-    if (typeof meta !== 'object' || meta === null) return undefined;
-    const seconds: unknown = (meta as Record<string, unknown>)['retryAfterSeconds'];
-    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds < 0) return undefined;
-    // At least one second, exactly as `RateLimitDecision.retryAfterSeconds` is clamped: `0` reads
-    // as "retry now", which is the stampede a Retry-After exists to spread.
-    return Math.max(1, Math.ceil(seconds));
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * RFC-9457 `type`, per code. A URN, and deliberately not a URL: `type` is the document's PRIMARY
- * identifier for the problem KIND — a client switches on it — while `docs` is where a human goes
- * to read about it, and those stopped being the same string when `docs` became one wiki page for
- * every code. Collapsing `type` onto that page too would have given a 422 body-invalid and a 403
- * forbidden the same identifier, which is the one thing a `type` may not do.
- *
- * A URN has no host to resolve, so it cannot rot the way `https://ultimate.dev/errors/<code>` did
- * — it was never dereferenceable and never claimed to be, which RFC 9457 §3.1.1 explicitly allows.
- * `code` carries the same string as a plain member for a reader that would rather not parse a URI.
- */
-export const problemTypeFor = (code: string): string => `urn:ultimate:error:${singleLine(code)}`;
-
-/** RFC-9457 problem document. `code`/`cause`/`fix`/`docs` are our extensions. */
-export interface ProblemDocument {
-  readonly type: string;
-  readonly title: string;
-  readonly status: number;
-  readonly detail: string;
-  readonly instance: string | undefined;
-  readonly code: string;
-  readonly cause: string;
-  readonly fix: string;
-  readonly docs: string;
-  readonly requestId: string | undefined;
-}
-
-/** The title a caller gets for a failure the framework cannot name. */
-const INTERNAL_TITLE = 'unhandled server error';
-
-/**
- * The cause a caller gets for one. An unclassified 5xx has no `cause` of its own, so `factsOf`
- * falls through to the throwable's `message` — a driver's DSN, the row Postgres rejected, an
- * absolute path — and `toProblem` handed it to whoever asked. `error-page.ts` locked the BROWSER
- * out of exactly this and said so in its header; the two audiences then disagreed about one
- * condition. The real text is not lost: the `error-map` stage logs it as a redactable FIELD and
- * reports every 5xx to the error monitor, both keyed by the request id below.
- */
-const INTERNAL_CAUSE =
-  'the server failed while handling this request; the details are in this process\u2019s logs and ' +
-  'error reports, under this request id';
-
 /**
- * A 5xx nobody declared a status for — not the framework's table, not the app's
- * `registerErrorStatus` — or one whose code is `X_INTERNAL`. That is the discriminator, and not
- * `status >= 500` alone: a declared code has an authored cause, and blanking `X_DRAINING`'s would
- * take away the one instruction in it.
+ * The status SOMEBODY declared for a code — the framework or the app — or `undefined` when
+ * nobody did. The two questions `statusFor` used to answer at once are separate on purpose:
+ * "what do we answer" is always a number, and "did anyone classify this" is what `error-facts.ts`
+ * reads to decide whether a 5xx may carry the throwable's own words back to the caller.
  *
- * `X_INTERNAL` is in the framework's table and still belongs here, because it is the framework's
- * own word for "nobody classified this": `factsOf` mints it for a throwable carrying no code, and
- * core's `toError()` wraps a caught value into an `InternalError` whose cause is
- * `renderCauseValue(value)` — the driver's message, verbatim. Nothing in an `X_INTERNAL` is
- * actionable by the caller; the code and the request id are.
+ * Framework table first: `registerErrorStatus` already refuses those codes, so the order is
+ * belt-and-braces — but it is the belt that makes "the framework's statuses are fixed" true
+ * even if a future caller reaches the map some other way.
+ * `APP_ERROR_STATUS` is a `Map`, which is why its half never had `frameworkStatus`'s defect —
+ * prefer one for anything keyed by a value a caller chose.
  */
-const isUnclassifiedFailure = (code: string, status: number): boolean =>
-  status >= 500 &&
-  (code === 'X_INTERNAL' || (frameworkStatus(code) === undefined && !APP_ERROR_STATUS.has(code)));
+export const declaredStatusFor = (code: string): number | undefined =>
+  frameworkStatus(code) ?? APP_ERROR_STATUS.get(code);
 
-export const toProblem = (
-  error: unknown,
-  meta: { instance?: string; requestId?: string; dev?: boolean } = {},
-): ProblemDocument => {
-  const facts = factsOf(error);
-  const opaque = meta.dev !== true && isUnclassifiedFailure(facts.code, facts.status);
-  return {
-    type: problemTypeFor(facts.code),
-    title: opaque ? INTERNAL_TITLE : facts.title,
-    status: facts.status,
-    detail: opaque ? INTERNAL_CAUSE : facts.cause,
-    instance: meta.instance,
-    code: facts.code,
-    cause: opaque ? INTERNAL_CAUSE : facts.cause,
-    fix: facts.fix,
-    docs: facts.docs,
-    requestId: meta.requestId,
-  };
-};
-
-/** The exact three lines the terminal prints, reused by the overlay and `--json`. */
-export const renderErrorLines = (error: unknown): string => {
-  const facts = factsOf(error);
-  // The newlines here are the format's own. Every interpolated field goes through `singleLine`
-  // so a caller-controlled value cannot add a third one — this string is rendered into the dev
-  // overlay's `<pre>`, where HTML escaping does not help because a newline is not markup.
-  return [
-    `${singleLine(facts.code)}: ${singleLine(facts.title)}`,
-    `  cause: ${singleLine(facts.cause)}`,
-    `  fix:   ${singleLine(facts.fix)}`,
-  ].join('\n');
-};
+export const statusFor = (code: string): number => declaredStatusFor(code) ?? DEFAULT_STATUS;

package/src/errors.ts

@@ -30,9 +30,12 @@ export const HTTP_OWNED_ERROR_CODES = [
   'X_RATE_LIMIT_SCOPE_UNSET',
   'X_RATE_LIMIT_INVALID',
   'X_RATE_LIMIT_STORE_UNAVAILABLE',
+  'X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN',
   'X_TRUST_PROXY_UNSET',
   'X_OVERLOADED',
   'X_CSRF_BLOCKED',
+  'X_WEBHOOK_SIGNATURE_INVALID',
+  'X_WEBHOOK_SIGNATURE_STALE',
 ] as const;
 
 /**
@@ -83,9 +86,12 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   X_RATE_LIMIT_SCOPE_UNSET: 'the deployment has not said where the rate limiter keeps its counters',
   X_RATE_LIMIT_INVALID: 'a declared rate limit computes to numbers the limiter cannot run on',
   X_RATE_LIMIT_STORE_UNAVAILABLE: 'the shared rate-limit store did not answer, so nothing decided',
+  X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN: 'the tenant allowance names a bucket nothing declares',
   X_TRUST_PROXY_UNSET: 'proxy headers are trusted without saying how many proxies are in front',
   X_OVERLOADED: 'in-flight requests are at the configured ceiling',
   X_CSRF_BLOCKED: 'a credentialed write arrived from an origin that is not allowed to make it',
+  X_WEBHOOK_SIGNATURE_INVALID: 'the inbound webhook is not signed by the holder of this secret',
+  X_WEBHOOK_SIGNATURE_STALE: 'the inbound webhook is signed correctly and is too old to accept',
 };
 
 // Registered at module load, unconditionally, in one call, so core's registry renders OUR title
@@ -289,7 +295,7 @@ export const corsConfigInvalid = (reason: string): HttpError =>
   new HttpError({
     code: 'X_CORS_CONFIG_INVALID',
     cause: `cors config rejected: ${reason}`,
-    fix: "in app.config.ts set http.cors.credentials: false, or replace http.cors.origins: ['*'] with the exact origins allowed to call this app",
+    fix: "call configureHttp({ cors: { credentials: false } }) at module scope in a file under apps/*/, or replace origins: ['*'] with the exact origins allowed to call this app",
   });
 
 /**
@@ -303,7 +309,7 @@ export const cspDirectiveInvalid = (where: string, value: string): HttpError =>
   new HttpError({
     code: 'X_CSP_DIRECTIVE_INVALID',
     cause: `${where} is not a csp token: ${JSON.stringify(value)}`,
-    fix: 'in app.config.ts write one http.security.csp.extend entry per directive, each source its own array element — a directive name is [a-z][a-z0-9-]*, and no source may contain a space, a comma or a semicolon',
+    fix: 'in the configureHttp({ security: { csp: { extend } } }) call write one entry per directive, each source its own array element — a directive name is [a-z][a-z0-9-]*, and no source may contain a space, a comma or a semicolon',
   });
 
 export const routeConflict = (path: string, detail: string): HttpError =>
@@ -325,7 +331,7 @@ export const trustProxyUnset = (): HttpError =>
     code: 'X_TRUST_PROXY_UNSET',
     cause:
       'http.trustProxy is true and http.trustedProxyHops is not set, so x-forwarded-for would be read from a position the client controls',
-    fix: 'in app.config.ts set http.trustedProxyHops to the number of proxies that append to x-forwarded-for — 1 for a single ingress or ALB, 2 for a CDN in front of one — or set http.trustProxy: false when this process is reached directly',
+    fix: 'set TRUSTED_PROXY_HOPS in the deployment environment to the number of proxies that append to x-forwarded-for — 1 for a single ingress or ALB, 2 for a CDN in front of one — and leave it unset for a process that is reached directly; an embedder calling defineHttpConfig itself passes { trustProxy: true, trustedProxyHops: 1 }',
   });
 
 /**
@@ -351,7 +357,7 @@ export const overloaded = (inflight: number, ceiling: number): HttpError =>
   new HttpError({
     code: 'X_OVERLOADED',
     cause: `${inflight} requests are already in flight and http.maxInflight is ${ceiling}`,
-    fix: 'retry after the Retry-After header; to serve more at once raise http.maxInflight in app.config.ts, and add replicas to match',
+    fix: 'retry after the Retry-After header; to serve more at once call configureHttp({ maxInflight: 2000 }) at module scope in a file under apps/*/, and add replicas to match',
   });
 
 /**
@@ -362,7 +368,7 @@ export const csrfBlocked = (pathname: string, reason: string): HttpError =>
   new HttpError({
     code: 'X_CSRF_BLOCKED',
     cause: `${pathname} refused a credentialed write: ${reason}`,
-    fix: "call it with an Authorization header instead of the session cookie, add the calling origin to http.cors.origins in app.config.ts, or set http.csrf.mode: 'off' if this app has no cookie session at all",
+    fix: "call it with an Authorization header instead of the session cookie, add the calling origin to configureHttp({ cors: { origins } }), or configureHttp({ csrf: { mode: 'off' } }) if this app has no cookie session at all",
   });
 
 /**
@@ -374,6 +380,40 @@ export const requestTimedOut = (method: string, pathname: string, timeoutMs: num
   new HttpError({
     code: 'X_TIMEOUT',
     cause: `${method} ${pathname} did not finish within ${timeoutMs}ms`,
-    fix: 'pass ctx.signal to every outbound call (fetch(url, { signal: ctx.signal })) and call throwIfAborted(ctx) before expensive work, or raise http.requestTimeoutMs in app.config.ts',
+    fix: 'pass ctx.signal to every outbound call (fetch(url, { signal: ctx.signal })) and call throwIfAborted(ctx) before expensive work, or call configureHttp({ requestTimeoutMs: 60_000 }) at module scope in a file under apps/*/',
     meta: { timeoutMs },
   });
+
+/**
+ * The inbound delivery is not signed by the holder of this route's secret — a wrong secret, a
+ * body something rewrote in transit, or a header this format does not define.
+ *
+ * 401 rather than 400: the request is well formed and carried a CREDENTIAL, and the credential is
+ * what failed. Rather than 403, which means an authenticated caller was refused, and there is no
+ * authenticated caller here. `reason` names only what the framework chose — never the signature
+ * that arrived, never the secret, and never the body — because a `cause` reaches both the caller
+ * and the log store, and a credential in either is a leak wearing a diagnostic's clothes.
+ */
+export const webhookSignatureInvalid = (pathname: string, reason: string): HttpError =>
+  new HttpError({
+    code: 'X_WEBHOOK_SIGNATURE_INVALID',
+    cause: `${pathname} refused an inbound webhook: ${reason}`,
+    fix: 'sign the delivery with the secret this endpoint was registered under, or re-read the secret from your sender dashboard and pass it as verifyWebhookSignature(request, { secret })',
+  });
+
+/**
+ * Signed correctly, and outside the replay window. Its own code because the repair is a different
+ * one: a sender's clock, or a delivery being replayed off a capture. Same 401 — the credential is
+ * a TIMESTAMPED one, and this is the expiry half of it.
+ */
+export const webhookSignatureStale = (
+  pathname: string,
+  skewMs: number,
+  toleranceMs: number,
+): HttpError =>
+  new HttpError({
+    code: 'X_WEBHOOK_SIGNATURE_STALE',
+    cause: `${pathname} received a valid signature ${skewMs}ms from this clock, and the window is ${toleranceMs}ms`,
+    fix: 'sync the sending host clock with NTP, or widen the window with verifyWebhookSignature(request, { secret, toleranceMs: 600_000 }) if the sender queues deliveries for longer than that',
+    meta: { skewMs, toleranceMs },
+  });

package/src/index.ts

@@ -2,6 +2,18 @@
 // listed here is an implementation detail and may change without a major bump.
 
 export type { RenderMode } from '@ultimat3/core';
+// The wire format is `@ultimat3/core`'s and is RE-EXPORTED, never re-declared: it is one module at
+// the tier both halves can reach, because `@ultimat3/jobs` signs a delivery, this package verifies
+// one, and neither may import the other. Re-exported here so a receiver route needs one import.
+export {
+  isCanonicalWebhookField,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_SIGNATURE_VERSION,
+  WEBHOOK_TOPIC_HEADER,
+} from '@ultimat3/core';
+export type { AppHttpConfig, BootOwnedHttpKey } from './app-config';
+export { configuredHttp, configureHttp, mergeHttpConfig, resetHttpConfig } from './app-config';
 export { NEXT_PARAM, nextAfterSignIn, signInRedirect } from './auth-redirect';
 export type { HttpConfig, HttpConfigInput } from './config';
 export { defineHttpConfig, stripBasePath } from './config';
@@ -24,18 +36,20 @@ export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
 export { checkCsrf, DEFAULT_CSRF, selfOrigin } from './csrf';
 export type { Deadline } from './deadline';
 export { REQUEST_TIMEOUT_HEADER, resolveTimeoutMs, startDeadline } from './deadline';
-export type { ErrorFacts, ProblemDocument } from './error-map';
+export type { ErrorFacts, ProblemDocument } from './error-facts';
 export {
-  DEFAULT_STATUS,
-  ERROR_STATUS,
   factsOf,
   problemTypeFor,
-  registerErrorStatus,
   renderErrorLines,
-  resetErrorStatus,
   retryAfterOf,
-  statusFor,
   toProblem,
+} from './error-facts';
+export {
+  DEFAULT_STATUS,
+  ERROR_STATUS,
+  registerErrorStatus,
+  resetErrorStatus,
+  statusFor,
 } from './error-map';
 export type {
   ErrorPageAction,
@@ -73,6 +87,8 @@ export {
   serverNotStarted,
   trustProxyUnset,
   unauthenticated,
+  webhookSignatureInvalid,
+  webhookSignatureStale,
 } from './errors';
 export type { ForwardedInput, ForwardedSplit } from './forwarded';
 export {
@@ -107,6 +123,7 @@ export type {
   RateLimiter,
   RateLimitKeyParts,
   RateLimitScope,
+  RateLimitSpend,
   RateLimitStore,
 } from './rate-limit';
 export {
@@ -116,8 +133,9 @@ export {
   DEFAULT_RATE_LIMIT,
   memoryRateLimitStore,
   rateLimitDecision,
-  rateLimitKey,
+  rateLimitSpends,
   resolveRateLimitConfig,
+  TENANT_SCOPE,
   toBucket,
 } from './rate-limit';
 export { assertRouteBuckets, withRouteBuckets } from './rate-limit-buckets';
@@ -129,6 +147,7 @@ export {
   rateLimitNotShared,
   rateLimitScopeUnset,
   rateLimitStoreUnavailable,
+  tenantBucketUnknown,
 } from './rate-limit-errors';
 export type {
   PgExecutor,
@@ -185,3 +204,9 @@ export { createServer } from './server';
 export type { Stage, StageDoc, StageName, StagePhase, StageRun } from './stages';
 export type { InferOutput, Schema, ValidationOutcome } from './validate';
 export { formatIssue, validate, validateSync } from './validate';
+export type { VerifiedWebhook, WebhookVerifyOptions } from './webhook-verify';
+export {
+  DEFAULT_WEBHOOK_BODY_LIMIT,
+  DEFAULT_WEBHOOK_TOLERANCE_MS,
+  verifyWebhookSignature,
+} from './webhook-verify';

package/src/overlay.ts

@@ -2,7 +2,7 @@
 // `--json` emits, so a code/cause/fix string can never differ between the three
 // surfaces. Labels here ("cause", "fix", "notices") are protocol strings from the
 // error contract, not UI copy, so they are not routed through the i18n catalog.
-import { factsOf, renderErrorLines, toProblem } from './error-map';
+import { factsOf, renderErrorLines, toProblem } from './error-facts';
 import { acceptsHtml, escapeHtml } from './html-render';
 import { OVERLAY_STYLE } from './overlay-style';
 import { html } from './response';

package/src/pipeline.ts

@@ -237,6 +237,10 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
         // address — an identity from an untrusted hop authenticates, which is worse than none.
         peer: peerIdentity(forwarded),
         signal: deadline.signal,
+        // The number behind that signal. `traceHeaders()` in core reads it off the ambient
+        // context, so every outbound hop this request makes carries what is LEFT of the budget
+        // rather than letting the next service start a fresh one of its own.
+        deadlineAt: deadline.deadlineAt,
         // The context is what app code reaches through core's ALS; without the inbound headers
         // on it, a cookie the server itself set could never be read back on the next request,
         // and `ctx.session` had no way to exist.