@queue-it/fastly 3.6.0 → 4.4.3-beta.0

package/README.md

@@ -1,58 +1,156 @@
-# KnownUser.V3.Fastly
-
-The Queue-it Security Framework ensures that end-users are not able to access your online application without first going through the queue for any and all �protected� areas and paths on your sites.
-The queue system is implemented by adding a server-side (request-level) integration that protects your online application by redirecting users to a waiting room according to web traffic settings
-in the Queue-it GO Platform. After the integration is complete, queue system behavior and operations are managed in Queue-it�s Go Platform and/or via the Queue-it Admin API.
-
-This Fastly Queue-it Connector SDK (aka, Queue-it�s server-side KnownUser connector) uses a Compute@Edge service to integrate Queue-it's functionality into Fastly's network. 
-
-A Wasm service is required to utilize this connector.
-
->You can find the latest released version [here](https://github.com/queueit/KnownUser.V3.Fastly/releases/latest).
-
-## Introduction
-
-When a user makes a request to your Fastly service our connector validates the request and if it is needed, it will redirect the user to the waiting room. After waiting in the waiting room,
-the queue engine will redirect the user back to your end attaching a query string parameter ( `queueittoken` ) containing some information about the user to the URL.
-The most important fields of the `queueittoken` are:
-
-- q - The user's unique queue identifier
-- ts - A timestamp of how long this redirect is valid
-- h - A hash of the token
-
-After the user returns from the queue, the connector will let the user continue his request to your backend ( without redirecting to the queue since the request has a valid queueittoken as query string) .
-
-## Installation
-
-To install the connector you can use the Fastly Compute@Edge CLI or you can upload an archive file (TGZ format) in the Fastly service configuration page.  
-Once deployed, the connector can be customized and updated with specific configurations (protection schema) managed and exported from the Queue-it GO Platform.
-
-- Step 1: Clone this repository and setup your fastly.toml file using the Fastly CLI.
-- Step 2: Set your Customer Id, API Key, Secret Id, Queue-it and origin backends in `requestResponseHandler.ts`.
-- Step 3: Create a Queue-it origin in your service configuration page.  
-The address should be `{CustomerId}.queue-it.net`. Set **Override host** to the same value.
-- Step 4: Build and deploy the package.
-- Step 5: Create desired waiting room(s), triggers, and actions in GO. Then, save/publish the configuration.
-
-## Providing the queue configuration
-
-The recommended way is to use the Go Queue-it self-service portal to setup the configuration. 
-The configuration specifies a set of Triggers and Actions. A Trigger is an expression matching one, more or all URLs on your website.
-When a user enter your website and the URL matches a Trigger-expression the corresponding Action will be triggered.
-The Action specifies which waiting room the users should be send to.
-In this way you can specify which waiting room(s) should protect which page(s) on the fly without changing the server-side integration.
-
-## Protecting AJAX calls
-
-If you need to protect AJAX calls beside page loads you need to add the below JavaScript tags to your pages:
-
-```html
-<script type="text/javascript" src="//static.queue-it.net/script/queueclient.min.js"></script>
-<script
- data-queueit-intercept-domain="{YOUR_CURRENT_DOMAIN}"
-   data-queueit-intercept="true"
-  data-queueit-c="{YOUR_CUSTOMER_ID}"
-  type="text/javascript"
-  src="//static.queue-it.net/script/queueconfigloader.min.js">
-</script>
-```
+# KnownUser.V3.Fastly
+
+The Queue-it Security Framework ensures that end-users are not able to access your online application without first
+going through the queue for any and all `protected` areas and paths on your sites. The queue system is implemented by
+adding a server-side (request-level) integration that protects your online application by redirecting users to a waiting
+room according to web traffic settings in the Queue-it GO Platform. After the integration is complete, queue system
+behavior and operations are managed in Queue-it's Go Platform and/or via the Queue-it Admin API.
+
+This Fastly Queue-it Connector SDK (aka, Queue-it's server-side KnownUser connector) uses a Compute@Edge service to
+integrate Queue-it's functionality into Fastly's network.
+
+A Wasm service is required to utilize this connector.
+
+> You can find the latest released version [here](https://github.com/queueit/KnownUser.V3.Fastly/releases/latest).
+
+## Introduction
+
+When a user makes a request to your Fastly service our connector validates the request and if it is needed, it will
+redirect the user to the waiting room. After waiting in the waiting room, the queue engine will redirect the user back
+to your end attaching a query string parameter ( `queueittoken` ) containing some information about the user to the URL.
+The most important fields of the `queueittoken` are:
+
+- q - The user's unique queue identifier
+- ts - A timestamp of how long this redirect is valid
+- h - A hash of the token
+
+After the user returns from the queue, the connector will let the user continue his request to your backend ( without
+redirecting to the queue since the request has a valid queueittoken as query string) .
+
+## Installation
+
+There are two methods of installation:
+
+### As a standalone service
+
+- Go to the Fastly services page and create a new **Wasm** service.
+- Go to Domains and fill in the domain that you want your service to be reachable at. You may need to register a CNAME
+  record if you have your own domain.
+- Then click on *Origins* and add a new host that has the hostname of your origin server.  
+  You need to edit the Host and name it **origin**.
+- Create a second host that has the hostname of `{yourCustomerId}.queue-it.net` and name it **queue-it**.  
+  Edit the host, go to advanced options and fill in the same hostname in **Override host**
+- Go to **Resources -> Config stores** and create a new config store named `IntegrationConfiguration`.
+  - Add the following items in the config store (you can find these values in the Go Queue-It self-service platform):
+    - customerId: Your customer ID
+    - apiKey: The API key for your account
+    - secret: Your KnownUserV3 secret
+    - queueItOrigin: The name of the queue-it host, in this case it's `queue-it`  
+  - Go to **Linked Services** and click on `Link Service`
+    - Select your service and click `Next`
+    - Click `Link and activate` to link the `Config store` to your service. It should generate a new version
+  - You can verify that the `Config store` has been linked by going to your service and see it in the section `Config stores`
+- Download the latest package from the releases page and unarchive it.
+- Edit the `fastly.toml` file and copy the ID of your service (you can see this by opening up the service in Fastly) and
+  replace **{YourServiceId}** with it.
+- Archive the directory in the same format (tar.gz).
+- Go to `Package` in the Fastly service page and upload the package.
+- To finish up and deploy your service click on the **Activate** button.
+
+### Customizable service with the connector
+
+- Go to the Fastly services page and create a new **Wasm** service and copy it's ID.
+- Clone this repository and edit the fastly.toml file, make sure to set the `service_id` field to the ID you copied.
+- Then click on *Origins* and add a new host that has the hostname of your origin server.
+  You can name the host **origin** or whatever you choose.
+- Create a host that has the hostname of `{yourCustomerId}.queue-it.net` and name it **queue-it**.
+  Edit the host, go to advanced options and fill in the same hostname in **Override host**
+- Go to **Resources -> Config stores** and create a new config store named `IntegrationConfiguration`.
+  - Add the following items in the config store (you can find these values in the Go Queue-It self-service platform):
+    - customerId: Your customer ID
+    - apiKey: The API key for your account
+    - secret: Your KnownUserV3 secret
+    - queueItOrigin: The name of the queue-it host, in this case it's `queue-it`
+  - Go to **Linked Services** and click on `Link Service`
+    - Select your service and click `Next`
+    - Click `Link and activate` to link the `Config store` to your service. It should generate a new version
+  - You can verify that the `Config store` has been linked by going to your service and see it in the section `Config stores`
+- You need to add some code that uses this connector. Here is an example:
+
+```ts
+import {Fastly} from "@fastly/as-compute";
+import {onQueueITRequest, IntegrationDetails, onQueueITResponse} from "@queue-it/fastly";
+
+const req = Fastly.getClientRequest();
+
+// This is optional and can be null if it's specified in your Config Store
+const integrationDetails = new IntegrationDetails(
+        "QueueItOriginName",
+        "CustomerId",
+        "SecretKey",
+        "ApiKey");
+let res = onQueueITRequest(req, integrationDetails);
+
+if (res != null) {
+    Fastly.respondWith(res!);
+} else {
+    const myOrigin = 'Ticketania';
+    const cacheOverride = new Fastly.CacheOverride();
+    const res = Fastly.fetch(req, {
+        backend: myOrigin,
+        cacheOverride,
+    }).wait();
+    onQueueITResponse(res);
+    Fastly.respondWith(res);
+} 
+```
+
+- Build and deploy the package running `fastly compute build` and `fastly compute deploy` in the same directory.
+- Create desired waiting room(s), triggers, and actions in the Go Queue-It self-service platform.  
+  Then, save/publish the configuration.
+
+## Enqueue Token Settings
+
+The connector supports enqueue tokens, which are used to secure the queue redirect flow. These settings are read at runtime from the Fastly `IntegrationConfiguration` Config Store. They are optional — if not set, the defaults below apply.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enqueueTokenEnabled` | `"true"` | Enables enqueue token generation. Set to `"false"` to disable. |
+| `enqueueTokenValidityTime` | `"240000"` | Token validity time in milliseconds. |
+| `enqueueTokenKeyEnabled` | `"false"` | Enables key-based enqueue tokens. Set to `"true"` to enable. |
+
+To configure these, add them as items in the `IntegrationConfiguration` Config Store alongside the other settings (`customerId`, `apiKey`, `secret`, etc.) — either via the Fastly UI or the Fastly API.
+
+## Request Body Trigger Matching
+
+The connector supports matching triggers based on the request body content. This is disabled by default. When enabled, up to 2048 characters of the request body are read and passed to the SDK for trigger evaluation.
+
+To enable it, add the following key to the `IntegrationConfiguration` Config Store:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `requestBodyEnabled` | `"false"` | Set to `"true"` to enable request body trigger matching. |
+
+## Providing the queue configuration
+
+The recommended way is to use the Go Queue-it self-service portal to setup the configuration. The configuration
+specifies a set of Triggers and Actions. A Trigger is an expression matching one, more or all URLs on your website. When
+a user enter your website and the URL matches a Trigger-expression the corresponding Action will be triggered. The
+Action specifies which waiting room the users should be send to. In this way you can specify which waiting room(s)
+should protect which page(s) on the fly without changing the server-side integration.
+
+## Protecting AJAX calls
+
+If you need to protect AJAX calls beside page loads you need to add the below JavaScript tags to your pages:
+
+```html
+
+<script type="text/javascript" src="//static.queue-it.net/script/queueclient.min.js"></script>
+<script
+        data-queueit-intercept-domain="{YOUR_CURRENT_DOMAIN}"
+        data-queueit-intercept="true"
+        data-queueit-c="{YOUR_CUSTOMER_ID}"
+        type="text/javascript"
+        src="//static.queue-it.net/script/queueconfigloader.min.js">
+</script>
+```

package/package.json

@@ -1,28 +1,35 @@
 {
   "name": "@queue-it/fastly",
-  "version": "3.6.0",
+  "version": "4.4.3-beta.0",
   "description": "Queue-it connector for Fastly",
-  "main": "index.js",
+  "main": "src/index.ts",
+  "author": "devs@queue-it.com",
+  "repository": "https://github.com/queueit/KnownUser.V3.Fastly",
+  "license": "MIT",
+  "files": [
+    "package.json",
+    "README.md",
+    "src/helpers",
+    "src/fastlyCryptoProvider.ts",
+    "src/contextProvider.ts",
+    "src/helper.ts",
+    "src/integrationConfigProvider.ts",
+    "src/requestResponseHandler.ts",
+    "src/index.ts"
+  ],
   "scripts": {
-    "test": "npx asp --config assembly/__tests__/as-pect.config.js --verbose",
-    "asbuild:untouched": "asc assembly/index.ts --target debug",
-    "asbuild:optimized": "asc assembly/index.ts --target release",
-    "asbuild": "npm run asbuild:untouched && npm run asbuild:optimized",
+    "typecheck": "tsc --noEmit",
+    "bundle": "esbuild src/index.ts --bundle --outfile=bin/index.js --platform=node --target=es2022 && js-compute-runtime bin/index.js bin/main.wasm",
     "build": "fastly compute build",
     "deploy": "fastly compute deploy"
   },
-  "author": "devs@queue-it.com",
-  "license": "MIT",
   "dependencies": {
-    "@assemblyscript/loader": "^0.17.14",
-    "@fastly/as-compute": "^0.2.1",
-    "as-wasi": "^0.4.4",
-    "assemblyscript-json": "^1.0.0",
-    "assemblyscript-regex": "^1.6.3"
+    "@fastly/js-compute": "^3.0.0",
+    "@queue-it/connector-javascript": "^4.4.4",
+    "@queue-it/queue-token": "~1.0.4"
   },
   "devDependencies": {
-    "@as-pect/cli": "^5.0.1",
-    "@as-pect/core": "^5.0.1",
-    "assemblyscript": "^0.17.14"
+    "esbuild": "^0.27.3",
+    "typescript": "^5.4.0"
   }
 }

package/src/contextProvider.ts

@@ -0,0 +1,175 @@
+import {
+    DefaultEnqueueTokenProvider,
+    IConnectorContextProvider,
+    ICryptoProvider,
+    IEnqueueTokenProvider,
+    INormalizationProvider,
+    DefaultNormalizationProvider,
+    IHttpRequest,
+    IHttpResponse,
+} from '@queue-it/connector-javascript';
+import { Token, Payload } from '@queue-it/queue-token';
+import { FastlyCryptoProvider } from './fastlyCryptoProvider';
+
+export function getHttpHandler(req: Request, clientIp: string = '', bodyString: string = ''): FastlyHttpContextProvider {
+    return new FastlyHttpContextProvider(req, clientIp, bodyString);
+}
+
+export class FastlyHttpContextProvider implements IConnectorContextProvider {
+    isError: boolean = false;
+    private readonly _httpRequest: FastlyHttpRequest;
+    private readonly _httpResponse: FastlyHttpResponse;
+    private _enqueueTokenProvider: IEnqueueTokenProvider | null = null;
+    private readonly _normalizationProvider: INormalizationProvider;
+    private readonly _cryptoProvider: ICryptoProvider;
+
+    constructor(fReq: Request, clientIp: string = '', bodyString: string = '') {
+        this._httpRequest = new FastlyHttpRequest(fReq, clientIp, bodyString);
+        this._httpResponse = new FastlyHttpResponse();
+        this._normalizationProvider = new DefaultNormalizationProvider();
+        this._cryptoProvider = new FastlyCryptoProvider();
+    }
+
+    getHttpRequest(): IHttpRequest {
+        return this._httpRequest;
+    }
+
+    getHttpResponse(): IHttpResponse {
+        return this._httpResponse;
+    }
+
+    getCryptoProvider(): ICryptoProvider {
+        return this._cryptoProvider;
+    }
+
+    setEnqueueTokenProvider(
+        customerId: string,
+        secretKey: string,
+        validityTime: number,
+        clientIp: string,
+        withKey: boolean
+    ): void {
+        this._enqueueTokenProvider = new DefaultEnqueueTokenProvider(
+            customerId,
+            secretKey,
+            validityTime,
+            clientIp,
+            withKey,
+            Token,
+            Payload
+        );
+    }
+
+    setCustomEnqueueTokenProvider(provider: IEnqueueTokenProvider): void {
+        this._enqueueTokenProvider = provider;
+    }
+
+    getEnqueueTokenProvider(): IEnqueueTokenProvider | null {
+        return this._enqueueTokenProvider;
+    }
+
+    getNormalizationProvider(): INormalizationProvider {
+        return this._normalizationProvider;
+    }
+
+    getResponseHeaders(): Headers {
+        return this._httpResponse.getHeaders();
+    }
+}
+
+class FastlyHttpRequest implements IHttpRequest {
+    private _parsedCookieDic: Record<string, string> | null = null;
+
+    constructor(private baseReq: Request, private _clientIp: string = '', private _bodyString: string = '') {}
+
+    getUserAgent(): string {
+        return this.getHeader('user-agent');
+    }
+
+    getHeader(name: string): string {
+        if (name.toLowerCase() === 'x-queueit-clientip')
+            return this.getUserHostAddress();
+
+        return this.baseReq.headers.get(name) || '';
+    }
+
+    getAbsoluteUri(): string {
+        return this.baseReq.url;
+    }
+
+    getUserHostAddress(): string {
+        return this._clientIp || this.baseReq.headers.get('Fastly-Client-IP') || '';
+    }
+
+    getCookieValue(name: string): string | undefined {
+        if (!this._parsedCookieDic) {
+            this._parsedCookieDic = this._parseCookies(this.getHeader('cookie'));
+        }
+
+        const cookieValue = this._parsedCookieDic[name];
+        if (cookieValue) {
+            try {
+                return decodeURIComponent(cookieValue);
+            } catch {
+                return;
+            }
+        }
+
+        return;
+    }
+
+    getRequestBodyAsString(): string {
+        return this._bodyString;
+    }
+
+    private _parseCookies(cookieValue: string): Record<string, string> {
+        const parsedCookie: Record<string, string> = {};
+        cookieValue.split(';').forEach(function (cookie) {
+            if (cookie) {
+                const parts = cookie.split('=');
+                if (parts.length >= 2) parsedCookie[parts[0].trim()] = parts[1].trim();
+            }
+        });
+        return parsedCookie;
+    }
+}
+
+class FastlyHttpResponse implements IHttpResponse {
+    private readonly headers: Headers;
+
+    constructor() {
+        this.headers = new Headers();
+    }
+
+    setCookie(
+        cookieName: string,
+        cookieValue: string,
+        domain: string,
+        expiration: number,
+        httpOnly: boolean,
+        isSecure: boolean
+    ): void {
+        const expirationDate = new Date(expiration * 1000);
+
+        let setCookieString = `${cookieName}=${encodeURIComponent(cookieValue)}; expires=${expirationDate.toUTCString()};`;
+
+        if (domain) {
+            setCookieString += ` domain=${domain};`;
+        }
+
+        if (httpOnly) {
+            setCookieString += ' HttpOnly;';
+        }
+
+        if (isSecure) {
+            setCookieString += ' Secure;';
+        }
+
+        setCookieString += ' path=/';
+        this.headers.append('set-cookie', setCookieString);
+    }
+
+    getHeaders(): Headers {
+        return this.headers;
+    }
+}

package/src/fastlyCryptoProvider.ts

@@ -0,0 +1,8 @@
+import { ICryptoProvider } from '@queue-it/connector-javascript';
+import { hmacString } from './helpers/crypto';
+
+export class FastlyCryptoProvider implements ICryptoProvider {
+    getSha256Hash(secretKey: string, plaintext: string): string {
+        return hmacString(secretKey, plaintext);
+    }
+}

package/src/helper.ts

@@ -0,0 +1,11 @@
+export class QueueITHelper {
+  static readonly KUP_VERSION: string = "fastly-4.4.3";
+
+  static addKUPlatformVersion(redirectQueueUrl: string): string {
+    return redirectQueueUrl + "&kupver=" + QueueITHelper.KUP_VERSION;
+  }
+}
+
+export interface RequestLogger {
+  log(message: string): void;
+}