@specprotected/spec-proxy-aws-edge-lambda/README.md

Spec Proxy integration with AWS Edge@Lambda

# Spec Proxy AWS Edge Lambda API Integration

This document describes a method of integrating with Spec Proxy through an AWS@Lambda
CloudFront function.

This library is created specifically for AWS Edge@Lambdas, and will not work for other Cloud Service Providers. 

If you are not using AWS, check the links to see other platform-specific examples:
- [Cloudflare](https://www.npmjs.com/package/@specprotected/spec-proxy-cloudflare-worker)
- [Fastly](https://www.npmjs.com/package/@specprotected/spec-proxy-fastly-worker)
- [Akamai](https://www.npmjs.com/package/@specprotected/spec-proxy-akamai-worker)
- [Generic Service Worker Lib](https://www.npmjs.com/package/@specprotected/spec-proxy-service-worker)

**Please contact your Spec representative for more details or to ask any questions.**

## What is an Edge@Lambda?

An Edge Lambda, or Lambda@Edge, is a feature of AWS Lambda that allows you to run code closer to your end users by deploying it to AWS CloudFront locations worldwide. This enables low-latency and highly responsive interactions by executing functions in response to CloudFront events, such as requests or responses. Edge Lambdas can be used for tasks like modifying HTTP requests and responses, performing A/B testing, implementing authentication and authorization, or generating dynamic content at the edge, thus enhancing the performance and scalability of web applications.

- [AWS Edge@Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html)
- [CloudFront](https://docs.aws.amazon.com/cloudfront/)

## Why use an Edge@Lambda with Spec Proxy?

Edge Workers allow you to integrate with Spec Proxy at the scale of the CDN provider. With
our simple library implementation, everything is processed in the background so customer
requests receive priority of handling. Integrating with our product is as easy as calling
a single function, and we provide you with configuration options to choose how to pass traffic
to Spec Proxy.

## Examples
For inline mode, we require only an "origin request" edge@lambda to send traffic to Spec. Our service can then add a required cookie. Since the traffic is not going through Spec, and only a copy is sent, we also require an "origin-response" edge@lambda to add the spec cookie on the request. 

### Origin Request Example:

``` javascript
import { specProxyProcessRequest } from "@specprotected/spec-proxy-aws-edge-lambda";
import { CloudFrontResponseEvent } from "aws-lambda";

const config = {
    disableSpecProxy: false,
    inlineMode: false 
}

export const handler = async (event: CloudFrontRequestEvent) => {
    return await specProxyProcessRequest(event, config);
}
```

Notes:
- This should exist as a part of a behavior on origin-request of an existing CloudFront distribution.
- It should also include the body in the request.

### Origin Response Example:

``` javascript
import { specProxyProcessResponse } from "@specprotected/spec-proxy-aws-edge-lambda";
import { CloudFrontResponseEvent } from "aws-lambda";

const config = {
    disablespecproxy: false,
    inlinemode: true
}

export const handler = async (event: CloudFrontResponseEvent) => {
    return await specProxyProcessResponse(event, config);
}

```

Notes:
- This should be on the same behavior as the other edge@lambda for origin-request
- This should be on the origin-response

## Configuration Options

We provide a few configuration options for how traffic should be handled by the
Cloudflare Worker.

| Variable           | Type    | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                              |
|--------------------|---------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `disableSpecProxy` | Boolean | `false` | Toggle between enabling or disabling Spec processing. When disabled (`true`), all traffic is routed directly to the customer's downstream origin, bypassing Spec completely. This setting causes all of the following settings to be ignored.                                                                                                                                                                            |
| `inlineMode`       | Boolean | `false` | Toggle between two available processing modes. Inline mode (`true`) works by forwarding traffic through the Spec Trust Cloud for processing. This mode enables inline mitigations. Mirror mode (`false`) creates a copy of traffic to send to the Spec Trust Cloud for processing while the original message is forwarded directly to the customer's downstream origin. This mode does not allow for inline mitigations. |
| `percentageOfIPs`  | Number  | `100`   | Number representing the percentage of all IP addresses which should have traffic routed through Spec. The remaining percentage of IPs will be routed directly to the customer's downstream origin. This can be used for progressive onboarding / rollout.                                                                                                                                                                |
| `customerKey`      | String  | none    | A key provided by Spec to validate that traffic came from a customer-controlled service worker                                                                                                                                                                                                                                                                                                                           |

The `inlineMode` configuration option is the only option that changes how Spec Proxy itself
behaves. For more details on what inline mode means and what features of Spec Proxy are
available to you when running in inline mode, please contact your Spec representative.

The `customerKey` option provides extra validation that we are only processing
traffic that originated from your service workers. In general, this is redundant
for inline processing, since we are processing traffic destined for the customer
  * [ ] origin and validating it with a customer-provided SSL certificate. For mirror
mode configurations, while we only allow traffic into Spec Proxy from your edge
platform's IP address ranges and do not return any data in the responses to
mirrored traffic, using the `customerKey` option is recommended. If this option
is provided, we will validate this key prior to processing any mirrored traffic.
The key is encrypted in transit with the rest of your mirrored traffic.

## Implementation Examples

There are two primary functions that are exported by this library:
- specProxyProcessRequest
  - This function should be used in an "origin request" lambda, so we process the request before the event reaches the downstream client origin. In mirror mode, this function simply packages a request for Spec, and returns the origin request to the origin. During inline operation, this function replaces the request origin object with one that points to Spec. 
- specProxyProcessResponse
  - This function should be included in an "origin response" edge lambda, which will add the required spec cookie.

- [Edge@Lambda Events](https://docs.aws.amazon.com/lambda/latest/dg/lambda-edge.html)

Please use the platform-specific library documentation for examples:
- [Cloudflare](https://www.npmjs.com/package/@specprotected/spec-proxy-cloudflare-worker)
- [Fastly](https://www.npmjs.com/package/@specprotected/spec-proxy-fastly-worker)
- [Akamai](https://www.npmjs.com/package/@specprotected/spec-proxy-akamai-worker)
- [Generic Service Worker Lib](https://www.npmjs.com/package/@specprotected/spec-proxy-service-worker)

### Integrating alongside another library

We return a request to help make it a simple integration alongside other products. Unfortunately,
though, Spec Proxy and other products may require the `event` object as an argument because this
provides access to a suite of tools from the [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API).
In order for Spec Proxy to properly record the incoming requests, it's best to call our library
first so we don't process data that has been manipulated by other libraries you may be using.

It can be useful to have a tool to provide the modified request to other libraries because the
`event` object that's passed in is not modifiable. Whether Spec Proxy is mirrored or inline, it will
create a new `Request` that must be used in the rest of your edge worker script. Here is how you can
trick Spec Proxy into using a wrapper object that replaces the `request` property. This is essentially
a proxy-object that allows us to modify parts of the incoming `event`, even though it is immutable.
This technique can be used to pass an `event` wrapper to other libraries as well. You may need to
provide access to some of the methods that other libraries require. The example below shows how to
proxy access to the `waitUntil` event, which is the only thing our library requires besides the `request`
object.

**Note:** The following example uses the generic service worker library, you should use the library specific to your platform and then implement the code below to wrap the `event` object. The generic service worker library below is incompatible with AWS. 

```javascript
import { specProxyProcess } from "@specprotected/spec-proxy-service-worker";

addEventListener("fetch", (event) => {
  // configuration to call our Spec library
  let config = {
    inlineMode: true,
  };

  // example of request modification happening prior to calling Spec Proxy
  let url = new URL(request.url);
  url.host = "https://somewhere.else"; // we modify the request in some way
  let request = new Request(url, event.request);

  // wrap up the event methods that the Spec Proxy library uses alongside the request
  let eventWrapper = {
    waitUntil: event.waitUntil.bind(event),
    request: request,
  };
  request = specProxyProcess(eventWrapper, config);

  event.respondWith(request);
});
```