@ultimat3/http 22.1.0 → 22.2.0

package/README.md

@@ -330,6 +330,39 @@ sign-in redirect, which keys on `X_UNAUTHENTICATED` alone.
 The sending half is `webhook()` in `@ultimat3/jobs`. Neither package may import the other, so the
 canonical string is stated in both and pinned by one literal vector asserted in both test files.
 
+## The exact body bytes
+
+`As of 2026-09-24`. `UltimateRequest#bodyBytes()` returns the body exactly as it was sent,
+whatever its content type. It is size-capped (`bodyLimitBytes`), read once and cached, and it is
+the same byte array that `bodyRaw()` parses. An action handler receives a `Ctx` and not the
+request, so it calls `useRequestBodyBytes()` to read the request in scope:
+
+```ts
+import { action, t } from '@ultimat3/action';
+import { useRequestBodyBytes, useRequestHeader } from '@ultimat3/http';
+import { allow } from '@ultimat3/policy';
+
+// The app's own check: SNS signs a canonical string of fields, a gateway signs the bytes.
+declare function verifySender(bytes: Uint8Array, header: string | null, body: string): Promise<void>;
+
+export const ingestSesEvent = action({
+  input: t.string.max(600_000),           // SNS posts text/plain: the decoded body
+  output: t.object({ ok: t.boolean }),
+  policy: allow('public'),                // the signature below authenticates the sender
+  async handle({ input }) {
+    const bytes = await useRequestBodyBytes();   // what the sender signed, byte for byte
+    await verifySender(bytes, useRequestHeader('x-signature'), input);
+    return { ok: true };
+  },
+});
+```
+
+| | |
+|---|---|
+| why not the decoded string | a decode can rewrite a BOM or an invalid UTF-8 byte, and the signature then fails with no visible cause |
+| one reader | `bodyRaw()` and `bodyBytes()` share one capped read, so an action that reads both reads the stream once |
+| off HTTP | `X_NO_REQUEST`: a job or an MCP call has no body bytes |
+
 ## Errors
 
 `X_ROUTE_NOT_FOUND` · `X_METHOD_NOT_ALLOWED` · `X_BODY_INVALID` · `X_UNAUTHENTICATED`

package/package.json

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

package/src/context.ts

@@ -127,6 +127,13 @@ export interface RequestContext extends Ctx {
    * "answer 303" can live without a second return protocol.
    */
   redirect: RedirectIntent | undefined;
+  /**
+   * The request body's exact bytes, through `UltimateRequest`'s one capped, cached read — set by
+   * its constructor, so there is still one reader and one limit. A slot and not the request: the
+   * context is what an action handler can reach (`useRequestBodyBytes()`), and a signature over
+   * the body (SNS, a payment gateway) is over bytes a decode would have rewritten.
+   */
+  readBody: (() => Promise<Uint8Array>) | undefined;
   response: Response | undefined;
   error: unknown;
 }
@@ -228,6 +235,7 @@ export const createRequestContext = (init: RequestContextInit): RequestContext =
     rateLimit: undefined,
     cache: undefined,
     redirect: undefined,
+    readBody: undefined,
     response: undefined,
     error: undefined,
   };
@@ -284,6 +292,18 @@ export const useRequestContext = (member = 'the request context'): RequestContex
  */
 export const useRequestHeaders = (): Headers => assertInRequest('request headers').requestHeaders;
 
+/**
+ * The exact bytes of the request in scope's body — what a webhook action verifies a signature
+ * over. `bodyRaw()` decodes `text/*` to a string, and a decode rewrites a BOM, an invalid byte
+ * and nothing else visibly: the signature then fails for a reason no log shows. Same cap, same
+ * cache as the parse the action's input came from, so reading both costs one read.
+ */
+export const useRequestBodyBytes = (): Promise<Uint8Array> => {
+  const read = assertInRequest('request body bytes').readBody;
+  if (read === undefined) throw noRequest('request body bytes');
+  return read();
+};
+
 export const useRequestHeader = (name: string): string | null => useRequestHeaders().get(name);
 
 /** The one way app code reads a cookie the browser sent — a session cookie included. */

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   asCtx,
   createRequestContext,
   elapsedMs,
+  useRequestBodyBytes,
   useRequestContext,
   useRequestCookie,
   useRequestHeader,

package/src/request.ts

@@ -43,10 +43,14 @@ export class UltimateRequest {
   readonly raw: Request;
   readonly ctx: RequestContext;
   #body: { parsed: unknown } | undefined;
+  #bytes: Promise<Uint8Array> | undefined;
 
   constructor(raw: Request, ctx: RequestContext) {
     this.raw = raw;
     this.ctx = ctx;
+    // Published on the context so an action handler — which gets a `Ctx`, never this object —
+    // reaches the same cached read (`useRequestBodyBytes()`), not a second reader of the stream.
+    ctx.readBody = () => this.bodyBytes();
   }
 
   get method(): string {
@@ -138,6 +142,16 @@ export class UltimateRequest {
     return parsed;
   }
 
+  /**
+   * The body exactly as sent, whatever its content type: size-capped, read once and cached, and
+   * the very bytes `bodyRaw()` parses. Empty for GET/HEAD and for no body. What a signature over
+   * the raw body is verified against, and what a signed-upload PUT stores.
+   */
+  bodyBytes(): Promise<Uint8Array> {
+    this.#bytes ??= this.#readBytes();
+    return this.#bytes;
+  }
+
   async body<Out>(schema: Schema<Out>): Promise<Out> {
     const outcome = await validate(schema, await this.bodyRaw());
     if (!outcome.ok) throw bodyInvalid(this.pathname, outcome.issues);
@@ -156,8 +170,8 @@ export class UltimateRequest {
     throw buildSkew(client, server);
   }
 
-  async #read(): Promise<unknown> {
-    if (this.method === 'GET' || this.method === 'HEAD') return undefined;
+  /** The declared length, refused up front when it is already over the cap. */
+  #declaredLength(): number | null {
     const limit = this.ctx.config.bodyLimitBytes;
     const header = this.header('content-length');
     // A missing content-length means "unknown", not "empty" — only an explicit 0 is
@@ -166,6 +180,25 @@ export class UltimateRequest {
     if (declared !== null && Number.isFinite(declared) && declared > limit) {
       throw bodyInvalid(this.pathname, [`body is ${declared} bytes, limit is ${limit}`]);
     }
+    return declared;
+  }
+
+  async #readBytes(): Promise<Uint8Array> {
+    if (this.method === 'GET' || this.method === 'HEAD') return new Uint8Array(0);
+    if (this.#declaredLength() === 0) return new Uint8Array(0);
+    // One capped read for every content type, multipart included: the parser runs on bytes this
+    // process already agreed to hold, never on a stream it hands to the runtime unbounded.
+    const limit = this.ctx.config.bodyLimitBytes;
+    const read = await readWithinLimit(this.raw.body, limit);
+    if ('over' in read) {
+      throw bodyInvalid(this.pathname, [`body is at least ${read.over} bytes, limit is ${limit}`]);
+    }
+    return read.bytes;
+  }
+
+  async #read(): Promise<unknown> {
+    if (this.method === 'GET' || this.method === 'HEAD') return undefined;
+    const declared = this.#declaredLength();
     const type = contentTypeOf(this.raw);
     // An EMPTY form is a form with no fields, never "no input": a button-only `<form>` posts
     // `content-length: 0`, and reading that as `undefined` failed every schema with 400.
@@ -182,13 +215,8 @@ export class UltimateRequest {
     }
     if (declared === 0) return form ? {} : undefined;
 
-    // One capped read for every content type, multipart included: the parser runs on bytes this
-    // process already agreed to hold, never on a stream it hands to the runtime unbounded.
-    const read = await readWithinLimit(this.raw.body, limit);
-    if ('over' in read) {
-      throw bodyInvalid(this.pathname, [`body is at least ${read.over} bytes, limit is ${limit}`]);
-    }
-    if (read.bytes.byteLength === 0) return form ? {} : undefined;
+    const bytes = await this.bodyBytes();
+    if (bytes.byteLength === 0) return form ? {} : undefined;
 
     if (type === 'multipart/form-data') {
       try {
@@ -196,7 +224,7 @@ export class UltimateRequest {
         // in — `Response` is the one multipart parser here, exactly as `Request` was.
         // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
         // `SharedArrayBuffer`, which `Response` does not accept.
-        const form = await new Response(new Uint8Array(read.bytes), {
+        const form = await new Response(new Uint8Array(bytes), {
           headers: { 'content-type': this.raw.headers.get('content-type') ?? type },
         }).formData();
         // `collectFields`, never `Object.fromEntries`: a repeated name is a LIST here for the
@@ -213,7 +241,7 @@ export class UltimateRequest {
       }
     }
 
-    const body = new TextDecoder().decode(read.bytes);
+    const body = new TextDecoder().decode(bytes);
     try {
       if (type === 'application/json' || type.endsWith('+json')) return JSON.parse(body);
       if (type === 'application/x-www-form-urlencoded') {