feat: add support for endpoints requiring client authentication using PKI (#393)

* feat: add support for endpoints requiring client authentication using PKI

This enables a global mTLS context for client requests using the native fetch
API. It can be used when custom endpoints require client authentication via
PKI.

* fix: Dockerfile syntax required for macOS

Set the Dockerfile syntax explictly to enable new features in Dockerfile.
The default syntax uses by Docker Desktop for macOS does not include support
for `--link` in the COPY command for example.

.env

@@ -19,6 +19,13 @@ OPENID_CLIENT_SECRET=
 OPENID_SCOPES="openid profile" # Add "email" for some providers like Google that do not provide preferred_username
 OPENID_PROVIDER_URL=https://huggingface.co # for Google, use https://accounts.google.com
 
+# Parameters to enable a global mTLS context for client fetch requests
+USE_CLIENT_CERTIFICATE=false
+CERT_PATH=#
+KEY_PATH=#
+CA_PATH=#
+CLIENT_KEY_PASSWORD=#
+REJECT_UNAUTHORIZED=true
 
 # 'name', 'userMessageToken', 'assistantMessageToken' are required
 MODELS=`[

Dockerfile

@@ -1,3 +1,4 @@
+# syntax=docker/dockerfile:1
 # read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
 # you will also find guides on how best to write your Dockerfile
 FROM node:19 as builder-production

README.md

@@ -152,7 +152,7 @@ MODELS=`[
 
 You can change things like the parameters, or customize the preprompt to better suit your needs. You can also add more models by adding more objects to the array, with different preprompts for example.
 
-#### Running your own models using a custom endpoint
+### Running your own models using a custom endpoint
 
 If you want to, instead of hitting models on the Hugging Face Inference API, you can run your own models locally.
 
@@ -171,7 +171,9 @@ To do this, you can add your own endpoints to the `MODELS` variable in `.env.loc
 
 If `endpoints` is left unspecified, ChatUI will look for the model on the hosted Hugging Face inference API using the model name.
 
-#### Custom endpoint authorization
+### Custom endpoint authorization
+
+#### Basic and Bearer
 
 Custom endpoints may require authorization, depending on how you configure them. Authentication will usually be set either with `Basic` or `Bearer`.
 
@@ -196,6 +198,14 @@ You can then add the generated information and the `authorization` parameter to
 
 ```
 
+#### Client Certificate Authentication (mTLS)
+
+Custom endpoints may require client certificate authentication, depending on how you configure them. To enable mTLS between Chat UI and your custom endpoint, you will need to set the `USE_CLIENT_CERTIFICATE` to `true`, and add the `CERT_PATH` and `KEY_PATH` parameters to your `.env.local`. These parameters should point to the location of the certificate and key files on your local machine. The certificate and key files should be in PEM format. The key file can be encrypted with a passphrase, in which case you will also need to add the `CLIENT_KEY_PASSWORD` parameter to your `.env.local`.
+
+If you're using a certificate signed by a private CA, you will also need to add the `CA_PATH` parameter to your `.env.local`. This parameter should point to the location of the CA certificate file on your local machine.
+
+If you're using a self-signed certificate, e.g. for testing or development purposes, you can set the `REJECT_UNAUTHORIZED` parameter to `false` in your `.env.local`. This will disable certificate validation, and allow Chat UI to connect to your custom endpoint.
+
 #### Models hosted on multiple custom endpoints
 
 If the model being hosted will be available on multiple servers/instances add the `weight` parameter to your `.env.local`. The `weight` will be used to determine the probability of requesting a particular endpoint.

src/lib/server/modelEndpoint.ts

@@ -1,7 +1,28 @@
-import { HF_ACCESS_TOKEN, HF_API_ROOT } from "$env/static/private";
+import {
+	HF_ACCESS_TOKEN,
+	HF_API_ROOT,
+	USE_CLIENT_CERTIFICATE,
+	CERT_PATH,
+	KEY_PATH,
+	CA_PATH,
+	CLIENT_KEY_PASSWORD,
+	REJECT_UNAUTHORIZED,
+} from "$env/static/private";
 import { sum } from "$lib/utils/sum";
 import type { BackendModel } from "./models";
 
+import { loadClientCertificates } from "$lib/utils/loadClientCerts";
+
+if (USE_CLIENT_CERTIFICATE === "true") {
+	loadClientCertificates(
+		CERT_PATH,
+		KEY_PATH,
+		CA_PATH,
+		CLIENT_KEY_PASSWORD,
+		REJECT_UNAUTHORIZED === "true"
+	);
+}
+
 /**
  * Find a random load-balanced endpoint
  */

src/lib/utils/loadClientCerts.ts

@@ -0,0 +1,50 @@
+import * as fs from "fs";
+import { setGlobalDispatcher, Agent } from "undici";
+
+/**
+ * Load client certificates for mutual TLS authentication. This function must be called before any HTTP requests are made.
+ * This is a global setting that affects all HTTP requests made by the application using the native fetch API.
+ *
+ * @param clientCertPath     Path to client certificate
+ * @param clientKeyPath      Path to client key
+ * @param caCertPath         Path to CA certificate [optional]
+ * @param clientKeyPassword  Password for client key [optional]
+ * @param rejectUnauthorized Reject unauthorized certificates.
+ *                           Only use for testing/development, not recommended in production environments [optional]
+ *
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * loadClientCertificates("cert.pem", "key.pem", "ca.pem", "password", false);
+ * ```
+ *
+ * @see
+ * [Undici Agent](https://undici.nodejs.org/#/docs/api/Agent)
+ * @see
+ * [Undici Dispatcher](https://undici.nodejs.org/#/docs/api/Dispatcher)
+ * @see
+ * [NodeJS Native Fetch API](https://nodejs.org/docs/latest-v19.x/api/globals.html#fetch)
+ */
+export function loadClientCertificates(
+	clientCertPath: string,
+	clientKeyPath: string,
+	caCertPath?: string,
+	clientKeyPassword?: string,
+	rejectUnauthorized?: boolean
+): void {
+	const clientCert = fs.readFileSync(clientCertPath);
+	const clientKey = fs.readFileSync(clientKeyPath);
+	const caCert = caCertPath ? fs.readFileSync(caCertPath) : undefined;
+	const agent = new Agent({
+		connect: {
+			cert: clientCert,
+			key: clientKey,
+			ca: caCert,
+			passphrase: clientKeyPassword,
+			rejectUnauthorized: rejectUnauthorized,
+		},
+	});
+
+	setGlobalDispatcher(agent);
+}