@ultimat3/http 25.0.0 → 25.2.0

package/CLAUDE.md

@@ -225,8 +225,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `readWithinLimit` and returns the raw text. The mac is checked BEFORE freshness
   (`X_WEBHOOK_SIGNATURE_STALE` means authentic and old); the window is `Math.abs`; the timestamp is
   digits-only; `:` is refused in id and topic; the comparison is `timingSafeEqual`
-  (`bun run secret-compare`). **The FORMAT is core's** (`packages/core/src/webhook-signature.ts`) —
-  never re-declared here.
+  (`bun run secret-compare`). **An empty `secret` is `X_CONFIG_INVALID`.**
+  **The FORMAT is core's** (`packages/core/src/webhook-signature.ts`) — never re-declared here.
 - Tests must not touch the network — the preload seals `fetch`. Socket tests live in `e2e/` (`bun test
   packages/http/e2e`), sealed; `start()` calls core's `markListening()`. Never unseal.
 

package/README.md

@@ -185,7 +185,7 @@ and one `insert … on conflict` per take (a peek is one `select`), so N replica
 line over the client the boot already opened; **never `Bun.sql`**, whose `.query` is `undefined`.
 
 ```ts
-import { db, type SqlFragment } from '@ultimat3/db';
+import { baseClient, dbExecutor } from '@ultimat3/db';
 import {
   httpServer,
   defineHttpConfig,
@@ -196,13 +196,9 @@ import {
 
 declare const routes: readonly Route[];
 
-// The client this process already opened, wrapped in one line. `@ultimat3/cli`'s `pgExecutorFor`
-// is this exact function, and it is what the boot passes when it installs the store for you.
-const client = db();
-const executor: PgExecutor = {
-  query: <R>(text: string, values: readonly unknown[]): Promise<readonly R[]> =>
-    client.query<R>({ text, values } satisfies SqlFragment),
-};
+// The pool this process already opened, never a request's open transaction — the boot builds
+// the same executor when it installs the store for you.
+const executor: PgExecutor = dbExecutor(baseClient);
 
 httpServer({
   routes,
@@ -368,6 +364,7 @@ export async function POST(request: Request): Promise<Response> {
 | a replay is detectable | `eventId` is signed and returned, so it cannot be moved in transit; the seen-set is your table, because the framework has nowhere to keep one |
 | moving the timestamp breaks it | the timestamp is inside the canonical string, so editing `t=` on a captured request invalidates the mac |
 | the raw bytes are what is verified | the body is read through core's counting reader — the same one `UltimateRequest` uses — so a sender that declares no length cannot make this handler hold an unbounded payload |
+| no secret is refused, never verified against | an empty or non-string `secret` (an unset `process.env.X`) throws `X_CONFIG_INVALID` before the request is read — a mac under an empty key is one anyone can compute. Only empty is refused, not short: the sender signs with any non-empty secret |
 | the mac is checked BEFORE the window | `X_WEBHOOK_SIGNATURE_STALE` means *authentic and old*, never *unreadable and old*, so an operator reading it goes to a clock or a replay |
 
 `X_WEBHOOK_SIGNATURE_INVALID` and `X_WEBHOOK_SIGNATURE_STALE` are both **401**: the request is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "25.0.0",
+  "version": "25.2.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.0.0",
-    "@ultimat3/i18n": "25.0.0",
-    "@ultimat3/schema": "25.0.0",
-    "@ultimat3/time": "25.0.0"
+    "@ultimat3/core": "25.2.0",
+    "@ultimat3/i18n": "25.2.0",
+    "@ultimat3/schema": "25.2.0",
+    "@ultimat3/time": "25.2.0"
   }
 }

package/src/error-map-tier-1.ts

@@ -70,4 +70,8 @@ export const TIER_1_ERROR_STATUS = {
   X_STORAGE_READ_FAILED: 500,
   // @ultimat3/storage — the object is under retention or a legal hold
   X_STORAGE_OBJECT_LOCKED: 409,
+  // @ultimat3/cache — a cached value the cache codec cannot encode (a cycle). The stack absorbs it
+  // through `bestEffort`; only a direct `LruCache.set` in a handler reaches a socket, and that is
+  // an authoring defect in the server's own code, never the caller's — hence 500.
+  X_CACHE_VALUE_UNENCODABLE: 500,
 } satisfies Readonly<Record<string, number>>;

package/src/errors.ts

@@ -129,11 +129,10 @@ export const bodyInvalid = (
     code: 'X_BODY_INVALID',
     cause: `${pathname} body rejected: ${issues.join('; ')}`,
     ...(meta === undefined ? {} : { meta }),
-    // `x schema show` is not a command — not in the registry and not in `PLANNED_COMMANDS`, so it
-    // exits `X_CLI_UNKNOWN_COMMAND`. The same axiom-4 inversion `x logs tail` had in `error-map`:
-    // the one instruction the reader is given fails when they run it. `x routes` ships, and
-    // `hasInputSchema` plus the route's name is what it prints.
-    fix: `x routes --json   # find ${pathname}, then send a body matching its input schema`,
+    // Only a route that declares `meta.input` reaches the body stage, and no action or query does
+    // (`invoke` and `runQuery` validate their own input, as `X_INPUT_INVALID`) — so this is a plain
+    // `runtime.ts` route, and `x routes --surface api` lists those by name since owner decision 2.
+    fix: `x routes --surface api --json   # find ${pathname}, a runtime.ts route, then send a body its meta.input schema accepts`,
   });
 
 /** At construction: a hole in a scope, or a prefix shadowing `/api` or `/_x`, never serves. */
@@ -447,3 +446,17 @@ export const webhookSignatureStale = (
     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 },
   });
+
+/**
+ * The receiver holds no secret. Not a weak key — NO key: an HMAC under '' is a mac anyone can
+ * compute, so verifying against it accepts every forged delivery. `X_CONFIG_INVALID` because the
+ * repair is the route's configuration and nothing a sender does can fix it. `shape` is `typeof`
+ * or "an empty string" — never the value, which is a credential when it is one.
+ */
+export const webhookSecretMissing = (shape: string): HttpError =>
+  new HttpError({
+    code: 'X_CONFIG_INVALID',
+    cause: `verifyWebhookSignature was given ${shape} as its secret, and a mac under an empty key is one anyone can compute — every forged delivery would verify`,
+    fix: "verifyWebhookSignature(request, { secret: process.env.WEBHOOK_SECRET ?? '' }) in the api/ route receiving it, with WEBHOOK_SECRET set in the deployment environment to the signing secret the sender shows for this endpoint — an unset variable is then refused here rather than verified against",
+    meta: { option: 'webhook secret' },
+  });

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,