@stone-js/aws-lambda-http-adapter 0.3.1 → 0.8.1

package/dist/index.js

@@ -1,47 +1,14 @@
-import { defaultLoggerResolver, IntegrationError, Adapter, AdapterEventBuilder, isNotEmpty, defaultKernelResolver, classDecoratorLegacyWrapper, addBlueprint } from '@stone-js/core';
+import { IntegrationError, Adapter, AdapterEventBuilder, defaultLoggerResolver, defaultKernelResolver, isNotEmpty, classDecoratorLegacyWrapper, addBlueprint } from '@stone-js/core';
+import { IncomingHttpEvent, HTTP_INTERNAL_SERVER_ERROR, BinaryFileResponse, OutgoingHttpResponse, CookieCollection, isIpTrusted, getHostname, getProtocol, httpCoreBlueprint, isMultipart, getCharset, getFilesUploads } from '@stone-js/http-core';
 import mime from 'mime';
 import accepts from 'accepts';
 import statuses from 'statuses';
-import { HTTP_INTERNAL_SERVER_ERROR, IncomingHttpEvent, BinaryFileResponse, OutgoingHttpResponse, isMultipart, getFilesUploads, CookieCollection, isIpTrusted, getHostname, getProtocol, getCharset, httpCoreBlueprint } from '@stone-js/http-core';
+import { cloneValue, deepMerge } from '@stone-js/config';
+import { getString } from '@stone-js/env';
 import { File } from '@stone-js/filesystem';
 import proxyAddr from 'proxy-addr';
 import bytes from 'bytes';
 import typeIs from 'type-is';
-import { getString } from '@stone-js/env';
-
-/**
- * Class representing an AwsLambdaHttpErrorHandler.
- */
-class AwsLambdaHttpErrorHandler {
-    logger;
-    /**
-     * Create an NodeHttpErrorHandler.
-     *
-     * @param options - NodeHttpErrorHandler options.
-     */
-    constructor({ blueprint }) {
-        this.logger = blueprint.get('stone.logger.resolver', defaultLoggerResolver)(blueprint);
-    }
-    /**
-     * Handle an error.
-     *
-     * @param error - The error to handle.
-     * @param context - The context of the adapter.
-     * @returns The raw response builder.
-     */
-    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';
-        const headers = new Headers({ 'Content-Type': contentType });
-        return context
-            .rawResponseBuilder
-            .add('headers', headers)
-            .add('statusCode', statusCode)
-            .add('statusMessage', statuses.message[statusCode]);
-    }
-}
 
 /**
  * Wrapper for HTTP raw responses in AWS Lambda.
@@ -105,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] : [];
     }
 }
 
@@ -214,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');
     }
@@ -255,6 +239,46 @@ class AwsLambdaHttpAdapter extends Adapter {
     }
 }
 
+/**
+ * Class representing an AwsLambdaHttpErrorHandler.
+ */
+class AwsLambdaHttpErrorHandler {
+    logger;
+    /**
+     * Create an NodeHttpErrorHandler.
+     *
+     * @param options - NodeHttpErrorHandler options.
+     */
+    constructor({ blueprint }) {
+        this.logger = blueprint.get('stone.logger.resolver', defaultLoggerResolver)(blueprint);
+    }
+    /**
+     * Handle an error.
+     *
+     * @param error - The error to handle.
+     * @param context - The context of the adapter.
+     * @returns The raw response builder.
+     */
+    handle(error, context) {
+        this.logger.error(error.message, { error });
+        // 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
+            .add('headers', headers)
+            .add('statusCode', statusCode)
+            .add('statusMessage', statuses.message[statusCode]);
+    }
+}
+
 /**
  * A constant representing the AWS Lambda HTTP platform identifier.
  *
@@ -264,6 +288,171 @@ class AwsLambdaHttpAdapter extends Adapter {
  */
 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.
  *
@@ -308,83 +497,14 @@ const metaAdapterBlueprintMiddleware = [
     { module: SetAwsLambdaHttpResponseResolverMiddleware, priority: 6 }
 ];
 
-/**
- * Class representing a FilesEventMiddleware.
- *
- * @author Mr. Stone <evensstone@gmail.com>
- */
-class FilesEventMiddleware {
-    /**
-     * The blueprint for resolving configuration and dependencies.
-     */
-    blueprint;
-    /**
-     * Create a FilesEventMiddleware.
-     *
-     * @param {blueprint} options - Options for creating the FilesEventMiddleware.
-     */
-    constructor({ blueprint }) {
-        this.blueprint = blueprint;
-    }
-    /**
-     * Handles the incoming event, processes it, and invokes the next middleware in the pipeline.
-     *
-     * @param context - The adapter context containing the raw event, execution context, and other data.
-     * @param next - The next middleware to be invoked in the pipeline.
-     * @returns A promise that resolves to the destination type after processing.
-     *
-     * @throws {AwsLambdaHttpAdapterError} If required components such as the rawEvent or IncomingEventBuilder are not provided.
-     */
-    async handle(context, next) {
-        if (context.rawEvent === undefined || context.incomingEventBuilder?.add === undefined) {
-            throw new AwsLambdaHttpAdapterError('The context is missing required components.');
-        }
-        if (isMultipart(this.normalizeEvent(context.rawEvent))) {
-            const options = this.blueprint.get('stone.http.files.upload', {});
-            const response = await getFilesUploads(this.normalizeEvent(context.rawEvent), options);
-            const method = response.fields.$method$;
-            context
-                .incomingEventBuilder
-                .add('files', response.files)
-                .add('body', response.fields);
-            // In fullstack forms, the method is spoofed and sent as a hidden field
-            isNotEmpty(method) && context.incomingEventBuilder.add('method', method);
-        }
-        return await next(context);
-    }
-    /**
-     * Normalize the incoming event to an IncomingMessage.
-     *
-     * @param rawEvent - The raw event to be normalized.
-     * @returns The normalized event.
-     */
-    normalizeEvent(rawEvent) {
-        let body = rawEvent.body;
-        if (typeof rawEvent.body === 'string') {
-            body = rawEvent.isBase64Encoded === true
-                ? Buffer.from(rawEvent.body, 'base64')
-                : Buffer.from(rawEvent.body, 'utf-8');
-        }
-        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']
-            }
-        };
-    }
-}
-/**
- * Meta Middleware for processing files uploads.
- */
-const MetaFilesEventMiddleware = { module: FilesEventMiddleware, isClass: true };
-
 /**
  * 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 {
     /**
@@ -394,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;
@@ -411,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);
     }
     /**
@@ -443,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.
      *
@@ -462,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;
     }
@@ -483,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);
     }
 }
 /**
@@ -564,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')) {
@@ -579,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;
@@ -591,6 +699,79 @@ class ServerResponseMiddleware {
  */
 const MetaServerResponseMiddleware = { module: ServerResponseMiddleware, isClass: true };
 
+/**
+ * Default blueprint configuration for the AWS Lambda Http Adapter.
+ *
+ * This blueprint defines the initial configuration for the AWS Lambda Http adapter
+ * within the Stone.js framework. It includes:
+ * - An alias for the AWS Lambda platform (`AWS_LAMBDA_HTTP_PLATFORM`).
+ * - A default resolver function (currently a placeholder).
+ * - Middleware, hooks, and state flags (`current`, `default`, `preferred`).
+ */
+const awsLambdaHttpAdapterBlueprint = {
+    stone: {
+        ...httpCoreBlueprint.stone,
+        blueprint: {
+            middleware: metaAdapterBlueprintMiddleware
+        },
+        adapters: [
+            {
+                current: false,
+                variant: 'server',
+                platform: AWS_LAMBDA_HTTP_PLATFORM,
+                middleware: [
+                    MetaIncomingEventMiddleware,
+                    MetaServerResponseMiddleware
+                ],
+                resolver: awsLambdaHttpAdapterResolver,
+                eventHandlerResolver: defaultKernelResolver,
+                errorHandlers: {
+                    default: { module: AwsLambdaHttpErrorHandler, isClass: true }
+                },
+                default: isNotEmpty(getString('AWS_LAMBDA_FUNCTION_NAME', ''))
+            }
+        ]
+    }
+};
+
+/**
+ * A Stone.js decorator that integrates the AWS Lambda HTTP Adapter with a class.
+ *
+ * This decorator modifies the class to seamlessly enable AWS Lambda HTTP as the
+ * execution environment for a Stone.js application. By applying this decorator,
+ * the class is automatically configured with the necessary blueprint for AWS Lambda HTTP.
+ *
+ * @template T - The type of the class being decorated. Defaults to `ClassType`.
+ * @param options - Optional configuration to customize the AWS Lambda HTTP Adapter.
+ *
+ * @returns A class decorator that applies the AWS Lambda HTTP adapter configuration.
+ *
+ * @example
+ * ```typescript
+ * import { AwsLambdaHttp } from '@stone-js/aws-lambda-http-adapter';
+ *
+ * @AwsLambdaHttp({
+ *   alias: 'MyAwsLambdaHttpAdapter',
+ *   current: true,
+ * })
+ * class App {
+ *   // Your application logic here
+ * }
+ * ```
+ */
+const AwsLambdaHttp = (options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        // 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);
+        }
+        addBlueprint(target, context, blueprint);
+    });
+};
+
 /**
  * Class representing a BodyEventMiddleware.
  *
@@ -626,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.
      *
@@ -643,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']
             }
         };
     }
@@ -667,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 {};
             }
@@ -725,223 +928,79 @@ class BodyEventMiddleware {
  */
 const MetaBodyEventMiddleware = { module: BodyEventMiddleware, isClass: true };
 
-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);
-
 /**
- * Default blueprint configuration for the AWS Lambda Http Adapter.
+ * Class representing a FilesEventMiddleware.
  *
- * This blueprint defines the initial configuration for the AWS Lambda Http adapter
- * within the Stone.js framework. It includes:
- * - An alias for the AWS Lambda platform (`AWS_LAMBDA_HTTP_PLATFORM`).
- * - A default resolver function (currently a placeholder).
- * - Middleware, hooks, and state flags (`current`, `default`, `preferred`).
+ * @author Mr. Stone <evensstone@gmail.com>
  */
-const awsLambdaHttpAdapterBlueprint = {
-    stone: {
-        ...httpCoreBlueprint.stone,
-        blueprint: {
-            middleware: metaAdapterBlueprintMiddleware
-        },
-        adapters: [
-            {
-                current: false,
-                variant: 'server',
-                platform: AWS_LAMBDA_HTTP_PLATFORM,
-                middleware: [
-                    MetaIncomingEventMiddleware,
-                    MetaServerResponseMiddleware
-                ],
-                resolver: awsLambdaHttpAdapterResolver,
-                eventHandlerResolver: defaultKernelResolver,
-                errorHandlers: {
-                    default: { module: AwsLambdaHttpErrorHandler, isClass: true }
-                },
-                default: isNotEmpty(getString('AWS_LAMBDA_FUNCTION_NAME', ''))
+class FilesEventMiddleware {
+    /**
+     * The blueprint for resolving configuration and dependencies.
+     */
+    blueprint;
+    /**
+     * Create a FilesEventMiddleware.
+     *
+     * @param {blueprint} options - Options for creating the FilesEventMiddleware.
+     */
+    constructor({ blueprint }) {
+        this.blueprint = blueprint;
+    }
+    /**
+     * Handles the incoming event, processes it, and invokes the next middleware in the pipeline.
+     *
+     * @param context - The adapter context containing the raw event, execution context, and other data.
+     * @param next - The next middleware to be invoked in the pipeline.
+     * @returns A promise that resolves to the destination type after processing.
+     *
+     * @throws {AwsLambdaHttpAdapterError} If required components such as the rawEvent or IncomingEventBuilder are not provided.
+     */
+    async handle(context, next) {
+        if (context.rawEvent === undefined || context.incomingEventBuilder?.add === undefined) {
+            throw new AwsLambdaHttpAdapterError('The context is missing required components.');
+        }
+        if (isMultipart(this.normalizeEvent(context.rawEvent))) {
+            const options = this.blueprint.get('stone.http.files.upload', {});
+            const response = await getFilesUploads(this.normalizeEvent(context.rawEvent), options);
+            const method = response.fields.$method$;
+            context
+                .incomingEventBuilder
+                .add('files', response.files)
+                .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);
+    }
+    /**
+     * Normalize the incoming event to an IncomingMessage.
+     *
+     * @param rawEvent - The raw event to be normalized.
+     * @returns The normalized event.
+     */
+    normalizeEvent(rawEvent) {
+        const headers = normalizeHeaders(rawEvent);
+        let body = rawEvent.body;
+        if (typeof rawEvent.body === 'string') {
+            body = rawEvent.isBase64Encoded === true
+                ? Buffer.from(rawEvent.body, 'base64')
+                : Buffer.from(rawEvent.body, 'utf-8');
+        }
+        return {
+            body,
+            headers: {
+                'content-type': headers['content-type'],
+                'content-length': headers['content-length'],
+                'transfer-encoding': headers['transfer-encoding']
             }
-        ]
+        };
     }
-};
-
+}
 /**
- * A Stone.js decorator that integrates the AWS Lambda HTTP Adapter with a class.
- *
- * This decorator modifies the class to seamlessly enable AWS Lambda HTTP as the
- * execution environment for a Stone.js application. By applying this decorator,
- * the class is automatically configured with the necessary blueprint for AWS Lambda HTTP.
- *
- * @template T - The type of the class being decorated. Defaults to `ClassType`.
- * @param options - Optional configuration to customize the AWS Lambda HTTP Adapter.
- *
- * @returns A class decorator that applies the AWS Lambda HTTP adapter configuration.
- *
- * @example
- * ```typescript
- * import { AwsLambdaHttp } from '@stone-js/aws-lambda-http-adapter';
- *
- * @AwsLambdaHttp({
- *   alias: 'MyAwsLambdaHttpAdapter',
- *   current: true,
- * })
- * class App {
- *   // Your application logic here
- * }
- * ```
+ * Meta Middleware for processing files uploads.
  */
-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);
-        }
-        // Add the modified blueprint to the target class.
-        addBlueprint(target, context, awsLambdaHttpAdapterBlueprint);
-    });
-};
+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 };