@ultimat3/http 24.0.0 → 25.1.0

package/src/stages.ts

@@ -6,6 +6,7 @@
 
 import {
   anonymousActor,
+  BUILD_ID_HEADER,
   inflightCount,
   isAnonymous,
   isDraining,
@@ -48,7 +49,7 @@ import type { UltimateRequest } from './request';
 import { addVary, problem, redirect } from './response';
 import { matchRoute, type Route, type RouteHandler, type RouteTable } from './router';
 import { responseSecurityHeaders } from './security-headers';
-import { validate } from './validate';
+import { validateBody } from './validate';
 
 export type StageName =
   | 'request-id'
@@ -173,12 +174,12 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       const answered = preflight(request.raw, config.cors);
       if (answered !== undefined) return answered;
 
-      ctx.clientBuildId = request.header(config.buildIdHeader);
+      ctx.clientBuildId = request.header(BUILD_ID_HEADER);
       // Stamped BEFORE the assertion, so the refusal carries it too. A skew answer that
       // withholds the server's own id tells a client it is stale without telling it what to
       // become — and the one caller that can act on that, the service worker holding the
       // stale id, then has no way to tell this 409 from any other.
-      if (config.buildId !== null) ctx.headers.set(config.buildIdHeader, config.buildId);
+      if (config.buildId !== null) ctx.headers.set(BUILD_ID_HEADER, config.buildId);
       request.assertBuild();
 
       // A `/<locale>/` prefix is stripped BEFORE the match, never by middleware: middleware wraps
@@ -273,7 +274,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
     body: async (request, ctx) => {
       const schema = ctx.route?.meta.input;
       if (schema === undefined) return undefined;
-      const outcome = await validate(schema, await request.bodyRaw());
+      const outcome = await validateBody(schema, await request.bodyRaw());
       if (!outcome.ok) throw bodyInvalid(ctx.url.pathname, outcome.issues);
       ctx.input = outcome.value;
       return undefined;
@@ -375,7 +376,15 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       // never handed a page. Which of the two a browser gets is the ENVIRONMENT — the overlay
       // prints the cause, the fix and the stack, which is what a visitor may never see.
       if (acceptsHtml(request.raw)) {
-        if (config.dev) {
+        // A 4xx is not a defect to debug, it is a page a visitor will see, so dev asks for the
+        // app's own file first (#492, O-492). A 5xx keeps the overlay, and so does a 4xx the app
+        // has no file for: in dev the diagnostic beats the framework's generic page.
+        // A throw from the hook is caught by `recoverWith` and degrades to the problem document.
+        const override =
+          config.dev && facts.status >= 500
+            ? undefined
+            : await hooks.errorPage?.(facts.status, ctx);
+        if (config.dev && override === undefined) {
           // Asked for inside the branch, never above it: the overlay is the only surface a notice
           // has, so a production process — or an agent that asked for json — must not pay a
           // diagnostic's per-request cost to produce findings nothing will render.
@@ -401,10 +410,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
             ...(seconds === undefined ? {} : { retryAfterSeconds: seconds }),
             signInPath: config.signInPath,
           },
-          // The app's own file, read per request by whoever mounted the hook. A throw here is
-          // caught by `recoverWith` and degrades to the problem document, which is the answer a
-          // page whose renderer failed can still give.
-          { override: await hooks.errorPage?.(facts.status, ctx), headers: retryAfter },
+          { override, headers: retryAfter },
         );
       }
       return problem(error, {

package/src/validate.ts

@@ -55,12 +55,12 @@ const outcome = <Out>(result: {
 export const validateSync = <Out>(schema: Schema<Out>, value: unknown): ValidationOutcome<Out> => {
   const result = schema['~standard'].validate(value);
   if (result instanceof Promise) {
-    return { ok: false, issues: ['schema is async; use validate() for request bodies'] };
+    return { ok: false, issues: ['schema is async; use validateBody() for request bodies'] };
   }
   return outcome<Out>(result);
 };
 
-export const validate = async <Out>(
+export const validateBody = async <Out>(
   schema: Schema<Out>,
   value: unknown,
 ): Promise<ValidationOutcome<Out>> => outcome<Out>(await schema['~standard'].validate(value));

package/src/webhook-verify.ts

@@ -25,6 +25,7 @@ import {
 import {
   bodyInvalid,
   httpCountInvalid,
+  webhookSecretMissing,
   webhookSignatureInvalid,
   webhookSignatureStale,
 } from './errors';
@@ -78,6 +79,20 @@ const assertFiniteBodyLimit = (maxBytes: number): number => {
   );
 };
 
+/**
+ * The secret is screened before the request is touched. `string` in the type is no guarantee: the
+ * usual caller passes `process.env.X`, and an unset one is `undefined` — which `webhookMac` turns
+ * into an UNKEYED hash, as it does '' into an HMAC under an empty key. Either way the mac is one
+ * anyone can compute. Only empty is refused, not short: the sender (`@ultimat3/jobs`) signs with
+ * any non-empty secret, and a receiver stricter than its sender refuses deliveries that are real.
+ */
+const assertWebhookSecret = (secret: unknown): string => {
+  if (typeof secret === 'string' && secret.length > 0) return secret;
+  throw webhookSecretMissing(
+    secret === '' ? 'an empty string' : `a value of type ${typeof secret}`,
+  );
+};
+
 export interface WebhookVerifyOptions {
   /** The shared secret for THIS sender. Never logged, never rendered into a refusal. */
   readonly secret: string;
@@ -118,6 +133,7 @@ export async function verifyWebhookSignature(
   request: Request,
   options: WebhookVerifyOptions,
 ): Promise<VerifiedWebhook> {
+  const secret = assertWebhookSecret(options.secret);
   const pathname = new URL(request.url).pathname;
   const signature = parseWebhookSignatureHeader(request.headers.get(WEBHOOK_SIGNATURE_HEADER));
   if (signature === undefined) {
@@ -149,7 +165,7 @@ export async function verifyWebhookSignature(
   // 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,
+    secret,
     timestampText: signature.timestampText,
     eventId,
     topic,