@ultimat3/http 22.0.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.0.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.0.0",
-    "@ultimat3/i18n": "22.0.0",
-    "@ultimat3/schema": "22.0.0",
-    "@ultimat3/time": "22.0.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/csrf.ts

@@ -5,7 +5,7 @@
 // went through. `setRedirect` exists so those form posts work without JS, which makes them a
 // first-class surface here rather than a legacy one.
 
-import { classifyAddress } from '@ultimat3/core';
+import { classifyAddress, proveSameOrigin } from '@ultimat3/core';
 import type { CorsConfig } from './cors';
 import { originListed } from './cors';
 import { HttpError } from './errors';
@@ -26,9 +26,6 @@ export const DEFAULT_CSRF: CsrfConfig = { mode: 'origin' };
 /** Methods with no side effects, per RFC 9110. A CSRF check on these is a check on nothing. */
 const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
 
-/** The complete `Sec-Fetch-Site` vocabulary. Anything else was written by a non-browser. */
-const KNOWN_SITES = new Set(['same-origin', 'same-site', 'cross-site', 'none']);
-
 export interface CsrfCheckInput {
   readonly method: string;
   /** The origin this app was reached on — scheme from `ctx.https`, host from the request URL. */
@@ -60,29 +57,21 @@ export const checkCsrf = (input: CsrfCheckInput): CsrfVerdict => {
   if (input.anonymous) return { ok: true };
   if (input.hasAuthorizationHeader) return { ok: true };
 
-  const site = input.secFetchSite;
-  if (site === 'same-origin' || site === 'none') return { ok: true };
-  if (input.origin === input.selfOrigin) return { ok: true };
+  // The rule itself is core's, shared with the sync node's upgrade: one answer to "did this
+  // come from this app?" on every surface an ambient credential reaches.
+  //
   // `originListed`, never `allowedOrigin`: that one answers the RESPONSE header, and for
   // `origins: ['*'], credentials: false` — the only wildcard `assertCorsConfig` admits — its
   // answer is `'*'`, which is not null and so read as "this origin is one we allow". A
   // credentialed cross-site POST from evil.test was therefore accepted by the check that exists
   // to refuse exactly it. An exact match is the only allowance a write may be built on.
-  if (originListed(input.cors, input.origin)) return { ok: true };
-  // Only the four values a browser can send are quoted back. Anything else is a client that
-  // wrote the header itself, and echoing what it wrote is how a rejected value reaches the log
-  // store and the response body — the same defect the error-map stage's log line had.
-  if (site !== null) {
-    const known = KNOWN_SITES.has(site) ? site : 'a value no browser sends';
-    return { ok: false, reason: `the request reported sec-fetch-site: ${known}` };
-  }
-  return {
-    ok: false,
-    reason:
-      input.origin === null
-        ? 'the request carried neither sec-fetch-site nor origin, so it cannot be shown to be same-origin'
-        : 'the origin it declares is not this app and is not listed in http.cors.origins',
-  };
+  return proveSameOrigin({
+    selfOrigins: [input.selfOrigin],
+    origin: input.origin,
+    secFetchSite: input.secFetchSite,
+    listed: (origin) => originListed(input.cors, origin),
+    listName: 'http.cors.origins',
+  });
 };
 
 /** The origin a browser compares against — the PUBLIC one, so a TLS-terminating proxy agrees. */

package/src/error-map.ts

@@ -425,6 +425,11 @@ export const ERROR_STATUS = {
   X_REALTIME_UNINSTALLED: 500,
   // Boot-time: a realtime config and its environment that disagree refuse before any request.
   X_REALTIME_TOPOLOGY: 500,
+  // The replicator's own Postgres connection failed TLS. A role that never answers a request, so the
+  // row keeps the table closed at 500, beside `X_REALTIME_TOPOLOGY`.
+  X_REPLICATION_TLS: 500,
+  // A browser page on a foreign origin asked for a socket — refused, not unauthenticated: 403.
+  X_SOCKET_ORIGIN_REFUSED: 403,
   X_RECORD_KEY_MISSING: 500,
   X_RECORD_REJECTED: 500,
   X_SYNC_UNCONFIGURED: 500,

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') {