@stone-js/aws-lambda-http-adapter 0.3.0 → 0.8.0

package/dist/index.js

@@ -3,6 +3,7 @@ import { IncomingHttpEvent, HTTP_INTERNAL_SERVER_ERROR, BinaryFileResponse, Outg
 import mime from 'mime';
 import accepts from 'accepts';
 import statuses from 'statuses';
+import { cloneValue, deepMerge } from '@stone-js/config';
 import { getString } from '@stone-js/env';
 import { File } from '@stone-js/filesystem';
 import proxyAddr from 'proxy-addr';
@@ -71,23 +72,40 @@ class RawHttpResponseWrapper {
      * ```
      */
     respond() {
-        return {
+        const headers = new Headers(this.options.headers ?? {});
+        const setCookies = this.extractSetCookies(headers);
+        headers.delete('set-cookie');
+        const response = {
             ...this.options,
             statusCode: this.options.statusCode ?? 500,
-            headers: this.normalizeHeaders(this.options.headers)
+            headers: Object.fromEntries(headers)
         };
+        // Emit multiple Set-Cookie correctly per trigger: v2/Function URLs use the `cookies` field,
+        // v1/ALB use `multiValueHeaders`. Folding them into a single comma-joined header (the old
+        // behaviour) is unparseable by browsers and leaks a cookie's attributes into the next.
+        if (setCookies.length > 0) {
+            if (this.options.version === 'v2') {
+                response.cookies = setCookies;
+            }
+            else {
+                response.multiValueHeaders = { ...this.options.multiValueHeaders, 'set-cookie': setCookies };
+            }
+        }
+        return response;
     }
     /**
-     * Normalizes the headers to a consistent format.
-     *
-     * Converts Headers or Record<string, string> to a normalized Record<string, string>
-     * with all keys in lowercase.
+     * Extract all `Set-Cookie` values from a Headers instance, tolerant of runtimes without
+     * `getSetCookie()`.
      *
-     * @param headers - The headers to normalize.
-     * @returns A normalized record of headers.
+     * @param headers - The response headers.
+     * @returns The raw `Set-Cookie` strings.
      */
-    normalizeHeaders(headers) {
-        return Object.fromEntries(new Headers(headers ?? {}));
+    extractSetCookies(headers) {
+        if (typeof headers.getSetCookie === 'function') {
+            return headers.getSetCookie();
+        }
+        const raw = headers.get('set-cookie');
+        return raw !== null && raw.length > 0 ? [raw] : [];
     }
 }
 
@@ -180,7 +198,7 @@ class AwsLambdaHttpAdapter extends Adapter {
      */
     async onStart() {
         if (typeof window === 'object') {
-            throw new AwsLambdaHttpAdapterError('This `AWSLambdaAdapter` must be used only in AWS Lambda context.');
+            throw new AwsLambdaHttpAdapterError('This `AwsLambdaHttpAdapter` must be used only in AWS Lambda context.');
         }
         await this.executeHooks('onStart');
     }
@@ -243,9 +261,15 @@ class AwsLambdaHttpErrorHandler {
      */
     handle(error, context) {
         this.logger.error(error.message, { error });
-        const statusCode = error.cause?.status ?? HTTP_INTERNAL_SERVER_ERROR;
-        const type = accepts(context.rawEvent).type(['json', 'html']);
-        const contentType = mime.getType(type !== false ? type : 'txt') ?? context.rawEvent.headers['content-type'] ?? 'text/plain';
+        // http-core's HttpError carries `statusCode` on the error itself; fall back to a cause and
+        // finally to 500. (Reading only `cause.status` turned every typed HTTP error into a 500.)
+        const statusCode = error.statusCode ??
+            error.cause?.statusCode ??
+            error.cause?.status ??
+            HTTP_INTERNAL_SERVER_ERROR;
+        const requestHeaders = context.rawEvent.headers ?? {};
+        const type = accepts({ headers: requestHeaders }).type(['json', 'html']);
+        const contentType = mime.getType(type !== false ? type : 'txt') ?? requestHeaders['content-type'] ?? 'text/plain';
         const headers = new Headers({ 'Content-Type': contentType });
         return context
             .rawResponseBuilder
@@ -264,6 +288,171 @@ class AwsLambdaHttpErrorHandler {
  */
 const AWS_LAMBDA_HTTP_PLATFORM = 'aws_lambda_http';
 
+/**
+ * Detect which AWS HTTP trigger produced the event.
+ *
+ * @param event - The raw Lambda event.
+ * @returns The trigger family.
+ */
+function detectEventVersion(event) {
+    const requestContext = event.requestContext;
+    if (requestContext?.elb !== undefined) {
+        return 'alb';
+    }
+    if (event.version === '2.0' || requestContext?.http !== undefined) {
+        return 'v2';
+    }
+    return 'v1';
+}
+/**
+ * Normalize headers to lower-cased keys, merging single and multi-value headers.
+ *
+ * @param event - The raw Lambda event.
+ * @returns Lower-cased headers with multi-value entries joined by `, `.
+ */
+function normalizeHeaders(event) {
+    const out = {};
+    const multi = event.multiValueHeaders;
+    if (multi !== null && multi !== undefined) {
+        for (const [name, values] of Object.entries(multi)) {
+            if (Array.isArray(values)) {
+                out[name.toLowerCase()] = values.join(', ');
+            }
+        }
+    }
+    const single = event.headers;
+    if (single !== null && single !== undefined) {
+        for (const [name, value] of Object.entries(single)) {
+            if (value !== undefined) {
+                out[name.toLowerCase()] = value;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Build the raw query string from whichever representation the trigger provides.
+ *
+ * v2 gives the fidelity-preserving `rawQueryString`. v1/ALB give an object (single value) and
+ * optionally `multiValueQueryStringParameters` (preferred, preserves repeated keys). Values are
+ * URL-encoded so repeated/array values survive.
+ *
+ * @param event - The raw Lambda event.
+ * @param version - The detected trigger family.
+ * @returns The raw query string (no leading `?`).
+ */
+function buildRawQueryString(event, version) {
+    if (version === 'v2' && typeof event.rawQueryString === 'string') {
+        return event.rawQueryString;
+    }
+    const multi = event.multiValueQueryStringParameters;
+    if (multi !== null && multi !== undefined) {
+        const params = new URLSearchParams();
+        for (const [key, values] of Object.entries(multi)) {
+            for (const value of values ?? []) {
+                params.append(key, value);
+            }
+        }
+        return params.toString();
+    }
+    const single = event.queryStringParameters;
+    if (single !== null && single !== undefined) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(single)) {
+            if (value !== undefined) {
+                params.append(key, value);
+            }
+        }
+        return params.toString();
+    }
+    return '';
+}
+/**
+ * Collect the raw cookie strings, regardless of trigger.
+ *
+ * v2 delivers `event.cookies: string[]`. v1/ALB deliver a single `Cookie` header (already merged
+ * into {@link NormalizedHttpEvent.headers}).
+ *
+ * @param event - The raw Lambda event.
+ * @param headers - The normalized headers.
+ * @returns The raw cookie strings.
+ */
+function collectCookies(event, headers) {
+    if (Array.isArray(event.cookies)) {
+        return event.cookies;
+    }
+    const header = headers.cookie;
+    return typeof header === 'string' && header.length > 0 ? header.split(/; */) : [];
+}
+/**
+ * Resolve the client source IP across triggers.
+ *
+ * @param event - The raw Lambda event.
+ * @param version - The detected trigger family.
+ * @param headers - The normalized headers.
+ * @returns The source IP (empty string if unknown).
+ */
+function resolveSourceIp(event, version, headers) {
+    const requestContext = event.requestContext;
+    if (version === 'v2') {
+        return String(requestContext?.http?.sourceIp ?? '');
+    }
+    if (version === 'v1') {
+        return String(requestContext?.identity?.sourceIp ?? '');
+    }
+    // ALB carries no identity; the client IP is the first hop in X-Forwarded-For.
+    return (headers['x-forwarded-for'] ?? '').split(',')[0].trim();
+}
+/**
+ * Normalize any AWS HTTP Lambda event into the canonical {@link NormalizedHttpEvent}.
+ *
+ * @param event - The raw Lambda event.
+ * @returns The normalized request.
+ */
+function normalizeHttpEvent(event) {
+    const version = detectEventVersion(event);
+    const headers = normalizeHeaders(event);
+    const requestContext = event.requestContext;
+    const method = String((version === 'v2' ? requestContext?.http?.method : undefined) ??
+        event.httpMethod ??
+        requestContext?.httpMethod ??
+        requestContext?.http?.method ??
+        'GET').toUpperCase();
+    const path = String((version === 'v2' ? (event.rawPath ?? requestContext?.http?.path) : undefined) ??
+        event.path ??
+        event.rawPath ??
+        '/');
+    return {
+        version,
+        method,
+        path,
+        headers,
+        rawQueryString: buildRawQueryString(event, version),
+        cookies: collectCookies(event, headers),
+        sourceIp: resolveSourceIp(event, version, headers),
+        isBase64Encoded: event.isBase64Encoded === true,
+        body: typeof event.body === 'string' ? event.body : undefined
+    };
+}
+/**
+ * Extract the raw request body exactly as received, decoding base64 to a Buffer when needed.
+ *
+ * This is what the adapter exposes as `metadata.rawBody`: the untouched payload the client sent,
+ * available to consumers even when no body-parsing middleware is installed. Binary payloads are
+ * returned as a `Buffer` (never a lossy UTF-8 round-trip); text payloads as a string. A
+ * non-string, non-base64 body (e.g. a pre-parsed object from a test/custom integration) is
+ * returned as-is.
+ *
+ * @param event - The raw Lambda event.
+ * @returns The raw body as a Buffer, string, the original value, or undefined.
+ */
+function getRawBody(event) {
+    if (typeof event.body === 'string') {
+        return event.isBase64Encoded === true ? Buffer.from(event.body, 'base64') : event.body;
+    }
+    return event.body;
+}
+
 /**
  * Adapter resolver for AWS Lambda HTTP adapter.
  *
@@ -276,154 +465,6 @@ const awsLambdaHttpAdapterResolver = (blueprint) => {
     return AwsLambdaHttpAdapter.create(blueprint);
 };
 
-function getDefaultExportFromCjs (x) {
-	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
-}
-
-var cjs;
-var hasRequiredCjs;
-
-function requireCjs () {
-	if (hasRequiredCjs) return cjs;
-	hasRequiredCjs = 1;
-
-	var isMergeableObject = function isMergeableObject(value) {
-		return isNonNullObject(value)
-			&& !isSpecial(value)
-	};
-
-	function isNonNullObject(value) {
-		return !!value && typeof value === 'object'
-	}
-
-	function isSpecial(value) {
-		var stringValue = Object.prototype.toString.call(value);
-
-		return stringValue === '[object RegExp]'
-			|| stringValue === '[object Date]'
-			|| isReactElement(value)
-	}
-
-	// see https://github.com/facebook/react/blob/b5ac963fb791d1298e7f396236383bc955f916c1/src/isomorphic/classic/element/ReactElement.js#L21-L25
-	var canUseSymbol = typeof Symbol === 'function' && Symbol.for;
-	var REACT_ELEMENT_TYPE = canUseSymbol ? Symbol.for('react.element') : 0xeac7;
-
-	function isReactElement(value) {
-		return value.$$typeof === REACT_ELEMENT_TYPE
-	}
-
-	function emptyTarget(val) {
-		return Array.isArray(val) ? [] : {}
-	}
-
-	function cloneUnlessOtherwiseSpecified(value, options) {
-		return (options.clone !== false && options.isMergeableObject(value))
-			? deepmerge(emptyTarget(value), value, options)
-			: value
-	}
-
-	function defaultArrayMerge(target, source, options) {
-		return target.concat(source).map(function(element) {
-			return cloneUnlessOtherwiseSpecified(element, options)
-		})
-	}
-
-	function getMergeFunction(key, options) {
-		if (!options.customMerge) {
-			return deepmerge
-		}
-		var customMerge = options.customMerge(key);
-		return typeof customMerge === 'function' ? customMerge : deepmerge
-	}
-
-	function getEnumerableOwnPropertySymbols(target) {
-		return Object.getOwnPropertySymbols
-			? Object.getOwnPropertySymbols(target).filter(function(symbol) {
-				return Object.propertyIsEnumerable.call(target, symbol)
-			})
-			: []
-	}
-
-	function getKeys(target) {
-		return Object.keys(target).concat(getEnumerableOwnPropertySymbols(target))
-	}
-
-	function propertyIsOnObject(object, property) {
-		try {
-			return property in object
-		} catch(_) {
-			return false
-		}
-	}
-
-	// Protects from prototype poisoning and unexpected merging up the prototype chain.
-	function propertyIsUnsafe(target, key) {
-		return propertyIsOnObject(target, key) // Properties are safe to merge if they don't exist in the target yet,
-			&& !(Object.hasOwnProperty.call(target, key) // unsafe if they exist up the prototype chain,
-				&& Object.propertyIsEnumerable.call(target, key)) // and also unsafe if they're nonenumerable.
-	}
-
-	function mergeObject(target, source, options) {
-		var destination = {};
-		if (options.isMergeableObject(target)) {
-			getKeys(target).forEach(function(key) {
-				destination[key] = cloneUnlessOtherwiseSpecified(target[key], options);
-			});
-		}
-		getKeys(source).forEach(function(key) {
-			if (propertyIsUnsafe(target, key)) {
-				return
-			}
-
-			if (propertyIsOnObject(target, key) && options.isMergeableObject(source[key])) {
-				destination[key] = getMergeFunction(key, options)(target[key], source[key], options);
-			} else {
-				destination[key] = cloneUnlessOtherwiseSpecified(source[key], options);
-			}
-		});
-		return destination
-	}
-
-	function deepmerge(target, source, options) {
-		options = options || {};
-		options.arrayMerge = options.arrayMerge || defaultArrayMerge;
-		options.isMergeableObject = options.isMergeableObject || isMergeableObject;
-		// cloneUnlessOtherwiseSpecified is added to `options` so that custom arrayMerge()
-		// implementations can use it. The caller may not replace it.
-		options.cloneUnlessOtherwiseSpecified = cloneUnlessOtherwiseSpecified;
-
-		var sourceIsArray = Array.isArray(source);
-		var targetIsArray = Array.isArray(target);
-		var sourceAndTargetTypesMatch = sourceIsArray === targetIsArray;
-
-		if (!sourceAndTargetTypesMatch) {
-			return cloneUnlessOtherwiseSpecified(source, options)
-		} else if (sourceIsArray) {
-			return options.arrayMerge(target, source, options)
-		} else {
-			return mergeObject(target, source, options)
-		}
-	}
-
-	deepmerge.all = function deepmergeAll(array, options) {
-		if (!Array.isArray(array)) {
-			throw new Error('first argument should be an array')
-		}
-
-		return array.reduce(function(prev, next) {
-			return deepmerge(prev, next, options)
-		}, {})
-	};
-
-	var deepmerge_1 = deepmerge;
-
-	cjs = deepmerge_1;
-	return cjs;
-}
-
-var cjsExports = requireCjs();
-var deepmerge = /*@__PURE__*/getDefaultExportFromCjs(cjsExports);
-
 /**
  * Middleware to dynamically set response resolver for adapter.
  *
@@ -459,8 +500,11 @@ const metaAdapterBlueprintMiddleware = [
 /**
  * Middleware for handling incoming events and transforming them into Stone.js events.
  *
- * This class processes incoming HTTP requests, extracting relevant data such as URL, IP addresses,
- * headers, cookies, and more, and forwards them to the next middleware in the pipeline.
+ * It first normalizes the raw AWS event (API Gateway v1/v2, ALB, Function URLs) into a single
+ * canonical shape, then extracts URL, IP addresses, headers, cookies, query and the raw body,
+ * so the pipeline never has to reason about which trigger fired. The untouched request body is
+ * always exposed as `metadata.rawBody` — even when no body-parsing middleware is installed — so
+ * consumers can read the original payload (e.g. to verify a webhook signature).
  */
 class IncomingEventMiddleware {
     /**
@@ -470,7 +514,7 @@ class IncomingEventMiddleware {
     /**
      * Create an IncomingEventMiddleware instance.
      *
-     * @param {blueprint} options - Options containing the blueprint for resolving configuration and dependencies.
+     * @param options - Options containing the blueprint for resolving configuration and dependencies.
      */
     constructor({ blueprint }) {
         this.blueprint = blueprint;
@@ -487,23 +531,23 @@ class IncomingEventMiddleware {
         if ((context.rawEvent === undefined) || ((context.incomingEventBuilder?.add) === undefined)) {
             throw new AwsLambdaHttpAdapterError('The context is missing required components.');
         }
+        const event = normalizeHttpEvent(context.rawEvent);
         const proxyOptions = this.getProxyOptions();
         const cookieOptions = this.getCookieOptions();
-        const url = this.extractUrl(context.rawEvent, proxyOptions);
-        const ipAddresses = this.extractIpAddresses(context.rawEvent, proxyOptions);
         context
             .incomingEventBuilder
-            .add('url', url)
-            .add('ips', ipAddresses)
+            .add('url', this.extractUrl(event, proxyOptions))
+            .add('ips', this.extractIpAddresses(event, proxyOptions))
             .add('source', this.getSource(context))
-            .add('headers', context.rawEvent.headers)
-            // If not defined by other middleware
-            // In fullstack forms, the method is spoofed and sent as a hidden field
-            .addIf('method', this.getMethod(context.rawEvent))
-            .add('queryString', context.rawEvent.queryStringParameters)
-            .add('protocol', this.getProtocol(context.rawEvent, proxyOptions))
-            .add('cookies', CookieCollection.create(context.rawEvent.headers.cookie, cookieOptions, this.getCookieSecret()))
-            .add('ip', proxyAddr(this.toNodeMessage(context.rawEvent), isIpTrusted(proxyOptions.trustedIp, proxyOptions.untrustedIp)));
+            .add('headers', event.headers)
+            // Expose the untouched request body so any consumer can read it, regardless of parsing.
+            .add('metadata', { rawBody: getRawBody(context.rawEvent) })
+            // If not defined by other middleware; in fullstack forms the method is spoofed via a field.
+            .addIf('method', event.method)
+            .add('queryString', event.rawQueryString)
+            .add('protocol', this.getProtocol(event, proxyOptions))
+            .add('cookies', CookieCollection.create(event.cookies.join('; '), cookieOptions, this.getCookieSecret()))
+            .add('ip', proxyAddr(this.toNodeMessage(event), isIpTrusted(proxyOptions.trustedIp, proxyOptions.untrustedIp)));
         return await next(context);
     }
     /**
@@ -519,18 +563,6 @@ class IncomingEventMiddleware {
             rawContext: context.executionContext
         };
     }
-    /**
-     * Extracts the HTTP method from the incoming rawEvent.
-     *
-     * @param rawEvent - The incoming rawEvent.
-     * @returns The HTTP method string.
-     */
-    getMethod(rawEvent) {
-        return rawEvent.httpMethod ??
-            rawEvent.requestContext?.httpMethod ??
-            rawEvent.requestContext?.http?.method ??
-            'GET';
-    }
     /**
      * Extracts proxy-related options from the blueprint.
      *
@@ -538,7 +570,7 @@ class IncomingEventMiddleware {
      */
     getProxyOptions() {
         const defaultProxyOptions = { trusted: [], trustedIp: [], untrustedIp: [] };
-        const proxyOptions = this.blueprint.get('stone.http.proxies', defaultProxyOptions);
+        const proxyOptions = { ...this.blueprint.get('stone.http.proxies', defaultProxyOptions) };
         proxyOptions.trusted = this.blueprint.get('stone.http.hosts.trusted', []);
         return proxyOptions;
     }
@@ -559,58 +591,58 @@ class IncomingEventMiddleware {
         return this.blueprint.get('stone.http.cookie.secret', this.blueprint.get('stone.secret', ''));
     }
     /**
-     * Extracts and parses the URL from the incoming rawEvent.
+     * Extracts and parses the URL (including the query string) from the normalized event.
      *
-     * @param rawEvent - The incoming HTTP rawEvent.
+     * @param event - The normalized HTTP event.
      * @param options - Proxy options.
      * @returns The parsed URL object.
      */
-    extractUrl(rawEvent, options) {
-        const hostname = getHostname(this.getRemoteAddress(rawEvent), rawEvent.headers, options);
-        const proto = getProtocol(this.getRemoteAddress(rawEvent), rawEvent.headers, true, options);
-        return new URL(rawEvent.path ?? rawEvent.rawPath ?? '', `${String(proto)}://${String(hostname)}`);
+    extractUrl(event, options) {
+        const hostname = getHostname(event.sourceIp, event.headers, options);
+        const proto = getProtocol(event.sourceIp, event.headers, true, options);
+        const pathWithQuery = event.rawQueryString.length > 0 ? `${event.path}?${event.rawQueryString}` : event.path;
+        return new URL(pathWithQuery, `${String(proto)}://${String(hostname)}`);
     }
     /**
-     * Extracts a list of IP addresses from the incoming rawEvent.
+     * Extracts a list of IP addresses from the normalized event.
      *
-     * @param rawEvent - The incoming HTTP rawEvent.
+     * @param event - The normalized HTTP event.
      * @param options - Proxy options.
      * @returns An array of IP addresses.
      */
-    extractIpAddresses(rawEvent, options) {
+    extractIpAddresses(event, options) {
         const isTrusted = isIpTrusted(options.trustedIp, options.untrustedIp);
-        return proxyAddr.all(this.toNodeMessage(rawEvent), isTrusted).slice(1).reverse();
+        return proxyAddr.all(this.toNodeMessage(event), isTrusted).slice(1).reverse();
     }
     /**
-     * Converts the incoming rawEvent to a Node.js IncomingMessage.
+     * Converts the normalized event to a minimal Node.js IncomingMessage for `proxy-addr`.
+     *
+     * All standard forwarding headers are forwarded (not just `x-forwarded-for`) so proxy-addr can
+     * honour the deployment's trust configuration.
      *
-     * @param rawEvent - The incoming rawEvent.
+     * @param event - The normalized HTTP event.
      * @returns The converted IncomingMessage.
      */
-    toNodeMessage(rawEvent) {
+    toNodeMessage(event) {
         return {
-            connection: { remoteAddress: this.getRemoteAddress(rawEvent) },
-            headers: { 'x-forwarded-for': rawEvent.headers['x-forwarded-for'] ?? rawEvent.headers['X-Forwarded-For'] }
+            connection: { remoteAddress: event.sourceIp },
+            socket: { remoteAddress: event.sourceIp },
+            headers: {
+                forwarded: event.headers.forwarded,
+                'x-real-ip': event.headers['x-real-ip'],
+                'x-forwarded-for': event.headers['x-forwarded-for'] ?? event.sourceIp
+            }
         };
     }
     /**
-     * Determines the protocol from the incoming rawEvent.
+     * Determines the protocol from the normalized event.
      *
-     * @param rawEvent - The incoming rawEvent.
+     * @param event - The normalized HTTP event.
      * @param options - Proxy options.
      * @returns The protocol string.
      */
-    getProtocol(rawEvent, options) {
-        return getProtocol(this.getRemoteAddress(rawEvent), rawEvent.headers, true, options);
-    }
-    /**
-     * Retrieves the remote address from the incoming rawEvent.
-     * This method is used as a fallback when the remote address is not found in the rawEvent.
-     * @param rawEvent - The incoming rawEvent.
-     * @returns The remote address string.
-     */
-    getRemoteAddress(rawEvent) {
-        return rawEvent.requestContext?.http?.sourceIp ?? rawEvent.requestContext?.identity?.sourceIp ?? '';
+    getProtocol(event, options) {
+        return getProtocol(event.sourceIp, event.headers, true, options);
     }
 }
 /**
@@ -640,6 +672,7 @@ class ServerResponseMiddleware {
         }
         rawResponseBuilder
             .add('headers', context.outgoingResponse.headers)
+            .add('version', detectEventVersion(context.rawEvent))
             .add('statusCode', context.outgoingResponse.statusCode ?? 500)
             .add('statusMessage', context.outgoingResponse.statusMessage ?? statuses.message[context.outgoingResponse.statusCode ?? 500]);
         if (!context.incomingEvent.isMethod('HEAD')) {
@@ -655,8 +688,7 @@ class ServerResponseMiddleware {
                     : context.outgoingResponse.content;
                 rawResponseBuilder
                     .add('body', content)
-                    .add('isBase64Encoded', isBuffer)
-                    .add('charset', context.outgoingResponse.charset);
+                    .add('isBase64Encoded', isBuffer);
             }
         }
         return rawResponseBuilder;
@@ -729,12 +761,14 @@ const awsLambdaHttpAdapterBlueprint = {
  */
 const AwsLambdaHttp = (options = {}) => {
     return classDecoratorLegacyWrapper((target, context) => {
-        if (awsLambdaHttpAdapterBlueprint.stone?.adapters?.[0] !== undefined) {
-            // Merge provided options with the default AWS Lambda HTTP adapter blueprint.
-            awsLambdaHttpAdapterBlueprint.stone.adapters[0] = deepmerge(awsLambdaHttpAdapterBlueprint.stone.adapters[0], options);
+        // Clone the module-level default before merging so decorating a class never mutates the shared
+        // singleton (which would leak options across classes and tests). cloneValue recreates plain
+        // objects/arrays while keeping functions and class references intact.
+        const blueprint = cloneValue(awsLambdaHttpAdapterBlueprint);
+        if (blueprint.stone?.adapters?.[0] !== undefined) {
+            blueprint.stone.adapters[0] = deepMerge(blueprint.stone.adapters[0], options);
         }
-        // Add the modified blueprint to the target class.
-        addBlueprint(target, context, awsLambdaHttpAdapterBlueprint);
+        addBlueprint(target, context, blueprint);
     });
 };
 
@@ -773,16 +807,33 @@ class BodyEventMiddleware {
         }
         if (!isMultipart(this.toNodeMessage(context.rawEvent))) {
             const body = this.getBody(this.toNodeMessage(context.rawEvent), context.rawEvent);
-            const method = body.$method$;
+            const method = this.extractSpoofedMethod(body);
             context
                 .incomingEventBuilder
                 .add('body', body)
-                .add('metadata', body);
-            // In fullstack forms, the method is spoofed and sent as a hidden field
+                // Keep the untouched payload available even after parsing (webhook signatures, etc.).
+                .add('metadata', { rawBody: getRawBody(context.rawEvent) });
+            // In fullstack forms, the method is spoofed and sent as a hidden field.
             isNotEmpty(method) && context.incomingEventBuilder.add('method', method);
         }
         return await next(context);
     }
+    /**
+     * Extract a spoofed HTTP method from a parsed body, supporting both JSON objects and
+     * urlencoded bodies (whose fields live on a `URLSearchParams`, not as own properties).
+     *
+     * @param body - The parsed body.
+     * @returns The spoofed method, or undefined.
+     */
+    extractSpoofedMethod(body) {
+        if (body instanceof URLSearchParams) {
+            return body.get('$method$') ?? undefined;
+        }
+        if (typeof body === 'object' && body !== null) {
+            return body.$method$;
+        }
+        return undefined;
+    }
     /**
      * Convert the raw event into a Node.js IncomingMessage.
      *
@@ -790,11 +841,12 @@ class BodyEventMiddleware {
      * @returns The converted IncomingMessage.
      */
     toNodeMessage(rawEvent) {
+        const headers = normalizeHeaders(rawEvent);
         return {
             headers: {
-                'content-type': rawEvent.headers['content-type'] ?? rawEvent.headers['Content-Type'],
-                'content-length': rawEvent.headers['content-length'] ?? rawEvent.headers['Content-Length'],
-                'transfer-encoding': rawEvent.headers['transfer-encoding'] ?? rawEvent.headers['Transfer-Encoding']
+                'content-type': headers['content-type'],
+                'content-length': headers['content-length'],
+                'transfer-encoding': headers['transfer-encoding']
             }
         };
     }
@@ -814,50 +866,54 @@ class BodyEventMiddleware {
         const limit = bytes.parse(rawLimit) ?? 100000;
         const encoding = getCharset(message, defaultCharset);
         const type = typeIs(message, ['urlencoded', 'json', 'text', 'bin']) ?? defaultType;
-        const rawBodyContent = this.getNormalizedRawBody(rawEvent, encoding);
-        if (Buffer.byteLength(rawBodyContent, encoding) > limit) {
+        // Decode ONCE to a Buffer. Binary payloads must never round-trip through a lossy UTF-8 string
+        // (which corrupts any non-UTF-8 byte); the limit is measured on the true byte length.
+        const rawBuffer = this.getRawBuffer(rawEvent, encoding);
+        if (rawBuffer.byteLength > limit) {
             throw new AwsLambdaHttpAdapterError('Body payload exceeds configured limit.');
         }
-        return this.parseBodyContent(type, rawBodyContent, encoding);
+        return this.parseBodyContent(type, rawBuffer, encoding);
     }
     /**
-     * Get the normalized raw body from the event.
+     * Decode the request body into a Buffer, honouring base64 encoding.
      *
      * @param rawEvent - The raw event containing the body.
-     * @param encoding - The encoding to use for the body.
-     * @returns The normalized body as a string.
+     * @param encoding - The charset for a plain-text (non-base64) body.
+     * @returns The body as a Buffer.
      */
-    getNormalizedRawBody(rawEvent, encoding) {
+    getRawBuffer(rawEvent, encoding) {
         if (typeof rawEvent.body === 'string') {
             return rawEvent.isBase64Encoded === true
-                ? Buffer.from(rawEvent.body, 'base64').toString(encoding)
-                : rawEvent.body;
+                ? Buffer.from(rawEvent.body, 'base64')
+                : Buffer.from(rawEvent.body, encoding);
         }
         if (typeof rawEvent.body === 'object' && rawEvent.body !== null) {
-            return JSON.stringify(rawEvent.body);
+            return Buffer.from(JSON.stringify(rawEvent.body), encoding);
         }
-        return '';
+        return Buffer.alloc(0);
     }
     /**
      * Parse the body content based on the specified type and encoding.
      *
      * @param type - The content type of the body.
-     * @param body - The raw body content as a string.
+     * @param buffer - The raw body content as a Buffer.
      * @param encoding - The encoding of the body content.
      * @returns The parsed body content as an object, string, or Buffer.
      * @throws {AwsLambdaHttpAdapterError} If parsing fails.
      */
-    parseBodyContent(type, body, encoding) {
+    parseBodyContent(type, buffer, encoding) {
         try {
             switch (type) {
-                case 'json':
-                    return isNotEmpty(body) ? JSON.parse(body) : {};
+                case 'json': {
+                    const text = buffer.toString(encoding);
+                    return isNotEmpty(text) ? JSON.parse(text) : {};
+                }
                 case 'text':
-                    return body;
+                    return buffer.toString(encoding);
                 case 'urlencoded':
-                    return new URLSearchParams(body);
+                    return new URLSearchParams(buffer.toString(encoding));
                 case 'bin':
-                    return Buffer.from(body, encoding);
+                    return buffer; // Return the raw bytes untouched — no lossy re-encoding.
                 default:
                     return {};
             }
@@ -910,8 +966,10 @@ class FilesEventMiddleware {
             context
                 .incomingEventBuilder
                 .add('files', response.files)
-                .add('body', response.fields);
-            // In fullstack forms, the method is spoofed and sent as a hidden field
+                .add('body', response.fields)
+                // Keep the untouched multipart payload available (webhook signatures, re-streaming, etc.).
+                .add('metadata', { rawBody: getRawBody(context.rawEvent) });
+            // In fullstack forms, the method is spoofed and sent as a hidden field.
             isNotEmpty(method) && context.incomingEventBuilder.add('method', method);
         }
         return await next(context);
@@ -923,6 +981,7 @@ class FilesEventMiddleware {
      * @returns The normalized event.
      */
     normalizeEvent(rawEvent) {
+        const headers = normalizeHeaders(rawEvent);
         let body = rawEvent.body;
         if (typeof rawEvent.body === 'string') {
             body = rawEvent.isBase64Encoded === true
@@ -932,9 +991,9 @@ class FilesEventMiddleware {
         return {
             body,
             headers: {
-                'content-type': rawEvent.headers['content-type'] ?? rawEvent.headers['Content-Type'],
-                'content-length': rawEvent.headers['content-length'] ?? rawEvent.headers['Content-Length'],
-                'transfer-encoding': rawEvent.headers['transfer-encoding'] ?? rawEvent.headers['Transfer-Encoding']
+                'content-type': headers['content-type'],
+                'content-length': headers['content-length'],
+                'transfer-encoding': headers['transfer-encoding']
             }
         };
     }
@@ -944,4 +1003,4 @@ class FilesEventMiddleware {
  */
 const MetaFilesEventMiddleware = { module: FilesEventMiddleware, isClass: true };
 
-export { AWS_LAMBDA_HTTP_PLATFORM, AwsLambdaHttp, AwsLambdaHttpAdapter, AwsLambdaHttpAdapterError, AwsLambdaHttpErrorHandler, BodyEventMiddleware, FilesEventMiddleware, IncomingEventMiddleware, MetaBodyEventMiddleware, MetaFilesEventMiddleware, MetaIncomingEventMiddleware, MetaServerResponseMiddleware, RawHttpResponseWrapper, ServerResponseMiddleware, SetAwsLambdaHttpResponseResolverMiddleware, awsLambdaHttpAdapterBlueprint, awsLambdaHttpAdapterResolver, metaAdapterBlueprintMiddleware };
+export { AWS_LAMBDA_HTTP_PLATFORM, AwsLambdaHttp, AwsLambdaHttpAdapter, AwsLambdaHttpAdapterError, AwsLambdaHttpErrorHandler, BodyEventMiddleware, FilesEventMiddleware, IncomingEventMiddleware, MetaBodyEventMiddleware, MetaFilesEventMiddleware, MetaIncomingEventMiddleware, MetaServerResponseMiddleware, RawHttpResponseWrapper, ServerResponseMiddleware, SetAwsLambdaHttpResponseResolverMiddleware, awsLambdaHttpAdapterBlueprint, awsLambdaHttpAdapterResolver, buildRawQueryString, collectCookies, detectEventVersion, getRawBody, metaAdapterBlueprintMiddleware, normalizeHeaders, normalizeHttpEvent, resolveSourceIp };