feat: Add client fingerprint properties (tlsJA4, h2Fingerprint, ohFingerprint) (#1248)

Co-authored-by: Sy Brand <[email protected]>

Author: ebonura-fastly

documentation/docs/globals/FetchEvent/FetchEvent.mdx

@@ -31,6 +31,12 @@ It provides the [`event.respondWith()`](./prototype/respondWith.mdx) method, whi
         - : Either `null` or an ArrayBuffer containing the raw client certificate in the mutual TLS handshake message. It is in PEM format. Returns an empty ArrayBuffer if this is not mTLS or available.
     - `FetchEvent.client.tlsClientHello` _**readonly**_
         - : Either `null` or an ArrayBuffer containing the raw bytes sent by the client in the TLS ClientHello message.
+    - `FetchEvent.client.tlsJA4` _**readonly**_
+        - : Either `null` or a string representation of the JA4 fingerprint of the TLS ClientHello message.
+    - `FetchEvent.client.h2Fingerprint` _**readonly**_
+        - : Either `null` or a string representation of the HTTP/2 fingerprint for HTTP/2 connections. Returns `null` for HTTP/1.1 connections.
+    - `FetchEvent.client.ohFingerprint` _**readonly**_
+        - : Either `null` or a string representation of the Original Header fingerprint based on the order and presence of request headers.
 - `FetchEvent.server` _**readonly**_
     - : Information about the server receiving the request for the Fastly Compute service.
     - `FetchEvent.server.address` _**readonly**_

integration-tests/js-compute/fixtures/app/src/client.js

@@ -74,3 +74,41 @@ routes.set('/client/tlsProtocol', (event) => {
     );
   }
 });
+
+routes.set('/client/tlsJA4', (event) => {
+  if (isRunningLocally()) {
+    strictEqual(event.client.tlsJA4, null);
+  } else {
+    strictEqual(
+      typeof event.client.tlsJA4,
+      'string',
+      'typeof event.client.tlsJA4',
+    );
+  }
+});
+
+routes.set('/client/h2Fingerprint', (event) => {
+  if (isRunningLocally()) {
+    strictEqual(event.client.h2Fingerprint, null);
+  } else {
+    // h2Fingerprint may be null for HTTP/1.1 connections
+    const fp = event.client.h2Fingerprint;
+    strictEqual(
+      fp === null || typeof fp === 'string',
+      true,
+      'event.client.h2Fingerprint is null or string',
+    );
+  }
+});
+
+routes.set('/client/ohFingerprint', (event) => {
+  if (isRunningLocally()) {
+    strictEqual(event.client.ohFingerprint, null);
+  } else {
+    strictEqual(
+      typeof event.client.ohFingerprint,
+      'string',
+      'typeof event.client.ohFingerprint',
+    );
+  }
+});

integration-tests/js-compute/fixtures/app/tests.json

@@ -449,6 +449,9 @@
   "GET /client/tlsClientCertificate": {},
   "GET /client/tlsCipherOpensslName": {},
   "GET /client/tlsProtocol": {},
+  "GET /client/tlsJA4": {},
+  "GET /client/h2Fingerprint": {},
+  "GET /client/ohFingerprint": {},
   "GET /config-store": {
     "flake": true
   },

runtime/fastly/builtins/fetch-event.cpp

@@ -48,6 +48,18 @@ JSString *ja3(JSObject *obj) {
   JS::Value val = JS::GetReservedSlot(obj, static_cast<uint32_t>(ClientInfo::Slots::JA3));
   return val.isString() ? val.toString() : nullptr;
 }
+JSString *ja4(JSObject *obj) {
+  JS::Value val = JS::GetReservedSlot(obj, static_cast<uint32_t>(ClientInfo::Slots::JA4));
+  return val.isString() ? val.toString() : nullptr;
+}
+JSString *h2Fingerprint(JSObject *obj) {
+  JS::Value val = JS::GetReservedSlot(obj, static_cast<uint32_t>(ClientInfo::Slots::H2Fingerprint));
+  return val.isString() ? val.toString() : nullptr;
+}
+JSString *ohFingerprint(JSObject *obj) {
+  JS::Value val = JS::GetReservedSlot(obj, static_cast<uint32_t>(ClientInfo::Slots::OHFingerprint));
+  return val.isString() ? val.toString() : nullptr;
+}
 JSObject *clientHello(JSObject *obj) {
   JS::Value val = JS::GetReservedSlot(obj, static_cast<uint32_t>(ClientInfo::Slots::ClientHello));
   return val.isObject() ? val.toObjectOrNull() : nullptr;
@@ -208,6 +220,81 @@ bool ClientInfo::tls_ja3_md5_get(JSContext *cx, unsigned argc, JS::Value *vp) {
   return true;
 }
 
+bool ClientInfo::tls_ja4_get(JSContext *cx, unsigned argc, JS::Value *vp) {
+  METHOD_HEADER(0);
+
+  JS::RootedString result(cx, ja4(self));
+  if (!result) {
+    auto res = host_api::HttpReq::http_req_downstream_tls_ja4();
+    if (auto *err = res.to_err()) {
+      HANDLE_ERROR(cx, *err);
+      return false;
+    }
+
+    if (!res.unwrap().has_value()) {
+      args.rval().setNull();
+      return true;
+    }
+
+    auto ja4_str = std::move(res.unwrap().value());
+    result.set(JS_NewStringCopyN(cx, ja4_str.ptr.get(), ja4_str.len));
+    JS::SetReservedSlot(self, static_cast<uint32_t>(ClientInfo::Slots::JA4),
+                        JS::StringValue(result));
+  }
+  args.rval().setString(result);
+  return true;
+}
+
+bool ClientInfo::h2_fingerprint_get(JSContext *cx, unsigned argc, JS::Value *vp) {
+  METHOD_HEADER(0);
+
+  JS::RootedString result(cx, h2Fingerprint(self));
+  if (!result) {
+    auto res = host_api::HttpReq::http_req_downstream_client_h2_fingerprint();
+    if (auto *err = res.to_err()) {
+      HANDLE_ERROR(cx, *err);
+      return false;
+    }
+
+    if (!res.unwrap().has_value()) {
+      args.rval().setNull();
+      return true;
+    }
+
+    auto h2fp_str = std::move(res.unwrap().value());
+    result.set(JS_NewStringCopyN(cx, h2fp_str.ptr.get(), h2fp_str.len));
+    JS::SetReservedSlot(self, static_cast<uint32_t>(ClientInfo::Slots::H2Fingerprint),
+                        JS::StringValue(result));
+  }
+  args.rval().setString(result);
+  return true;
+}
+
+bool ClientInfo::oh_fingerprint_get(JSContext *cx, unsigned argc, JS::Value *vp) {
+  METHOD_HEADER(0);
+
+  JS::RootedString result(cx, ohFingerprint(self));
+  if (!result) {
+    auto res = host_api::HttpReq::http_req_downstream_client_oh_fingerprint();
+    if (auto *err = res.to_err()) {
+      HANDLE_ERROR(cx, *err);
+      return false;
+    }
+
+    if (!res.unwrap().has_value()) {
+      args.rval().setNull();
+      return true;
+    }
+
+    auto ohfp_str = std::move(res.unwrap().value());
+    result.set(JS_NewStringCopyN(cx, ohfp_str.ptr.get(), ohfp_str.len));
+    JS::SetReservedSlot(self, static_cast<uint32_t>(ClientInfo::Slots::OHFingerprint),
+                        JS::StringValue(result));
+  }
+  args.rval().setString(result);
+  return true;
+}
+
 bool ClientInfo::tls_client_hello_get(JSContext *cx, unsigned argc, JS::Value *vp) {
   METHOD_HEADER(0);
 
@@ -323,6 +410,9 @@ const JSPropertySpec ClientInfo::properties[] = {
     JS_PSG("tlsCipherOpensslName", tls_cipher_openssl_name_get, JSPROP_ENUMERATE),
     JS_PSG("tlsProtocol", tls_protocol_get, JSPROP_ENUMERATE),
     JS_PSG("tlsJA3MD5", tls_ja3_md5_get, JSPROP_ENUMERATE),
+    JS_PSG("tlsJA4", tls_ja4_get, JSPROP_ENUMERATE),
+    JS_PSG("h2Fingerprint", h2_fingerprint_get, JSPROP_ENUMERATE),
+    JS_PSG("ohFingerprint", oh_fingerprint_get, JSPROP_ENUMERATE),
     JS_PSG("tlsClientCertificate", tls_client_certificate_get, JSPROP_ENUMERATE),
     JS_PSG("tlsClientHello", tls_client_hello_get, JSPROP_ENUMERATE),
     JS_PS_END,

runtime/fastly/builtins/fetch-event.h

@@ -15,6 +15,9 @@ class ClientInfo final : public builtins::BuiltinNoConstructor<ClientInfo> {
   static bool tls_protocol_get(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool tls_client_hello_get(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool tls_ja3_md5_get(JSContext *cx, unsigned argc, JS::Value *vp);
+  static bool tls_ja4_get(JSContext *cx, unsigned argc, JS::Value *vp);
+  static bool h2_fingerprint_get(JSContext *cx, unsigned argc, JS::Value *vp);
+  static bool oh_fingerprint_get(JSContext *cx, unsigned argc, JS::Value *vp);
   static bool tls_client_certificate_get(JSContext *cx, unsigned argc, JS::Value *vp);
 
 public:
@@ -27,6 +30,9 @@ class ClientInfo final : public builtins::BuiltinNoConstructor<ClientInfo> {
     Protocol,
     ClientHello,
     JA3,
+    JA4,
+    H2Fingerprint,
+    OHFingerprint,
     ClientCert,
     Count,
   };

runtime/fastly/host-api/fastly.h

@@ -532,6 +532,15 @@ int req_downstream_tls_raw_client_certificate(uint8_t *ret, size_t ret_len, size
 WASM_IMPORT("fastly_http_req", "downstream_tls_ja3_md5")
 int req_downstream_tls_ja3_md5(uint8_t *ret, size_t *nwritten);
 
+WASM_IMPORT("fastly_http_req", "downstream_tls_ja4")
+int req_downstream_tls_ja4(uint8_t *ret, size_t ret_len, size_t *nwritten);
+
+WASM_IMPORT("fastly_http_req", "downstream_client_h2_fingerprint")
+int req_downstream_client_h2_fingerprint(uint8_t *ret, size_t ret_len, size_t *nwritten);
+
+WASM_IMPORT("fastly_http_req", "downstream_client_oh_fingerprint")
+int req_downstream_client_oh_fingerprint(uint8_t *ret, size_t ret_len, size_t *nwritten);
+
 WASM_IMPORT("fastly_http_req", "new")
 int req_new(uint32_t *req_handle_out);
 

runtime/fastly/host-api/host_api.cpp

@@ -1807,6 +1807,90 @@ Result<std::optional<HostBytes>> HttpReq::http_req_downstream_tls_ja3_md5() {
   return res;
 }
 
+// http-req-downstream-tls-ja4: func() -> result<option<string>, error>
+Result<std::optional<HostString>> HttpReq::http_req_downstream_tls_ja4() {
+  TRACE_CALL()
+  Result<std::optional<HostString>> res;
+
+  fastly::fastly_host_error err;
+  fastly::fastly_world_string ret;
+  auto default_size = 128;
+  ret.ptr = static_cast<uint8_t *>(cabi_malloc(default_size, 4));
+  auto status = fastly::req_downstream_tls_ja4(ret.ptr, default_size, &ret.len);
+  if (status == FASTLY_HOST_ERROR_BUFFER_LEN) {
+    ret.ptr = static_cast<uint8_t *>(cabi_realloc(ret.ptr, default_size, 4, ret.len));
+    status = fastly::req_downstream_tls_ja4(ret.ptr, ret.len, &ret.len);
+  }
+  if (!convert_result(status, &err)) {
+    cabi_free(ret.ptr);
+    if (error_is_optional_none(err)) {
+      res.emplace(std::nullopt);
+    } else {
+      res.emplace_err(err);
+    }
+  } else {
+    res.emplace(make_host_string(ret));
+  }
+
+  return res;
+}
+
+// http-req-downstream-client-h2-fingerprint: func() -> result<option<string>, error>
+Result<std::optional<HostString>> HttpReq::http_req_downstream_client_h2_fingerprint() {
+  TRACE_CALL()
+  Result<std::optional<HostString>> res;
+
+  fastly::fastly_host_error err;
+  fastly::fastly_world_string ret;
+  auto default_size = 128;
+  ret.ptr = static_cast<uint8_t *>(cabi_malloc(default_size, 4));
+  auto status = fastly::req_downstream_client_h2_fingerprint(ret.ptr, default_size, &ret.len);
+  if (status == FASTLY_HOST_ERROR_BUFFER_LEN) {
+    ret.ptr = static_cast<uint8_t *>(cabi_realloc(ret.ptr, default_size, 4, ret.len));
+    status = fastly::req_downstream_client_h2_fingerprint(ret.ptr, ret.len, &ret.len);
+  }
+  if (!convert_result(status, &err)) {
+    cabi_free(ret.ptr);
+    if (error_is_optional_none(err)) {
+      res.emplace(std::nullopt);
+    } else {
+      res.emplace_err(err);
+    }
+  } else {
+    res.emplace(make_host_string(ret));
+  }
+
+  return res;
+}
+
+// http-req-downstream-client-oh-fingerprint: func() -> result<option<string>, error>
+Result<std::optional<HostString>> HttpReq::http_req_downstream_client_oh_fingerprint() {
+  TRACE_CALL()
+  Result<std::optional<HostString>> res;
+
+  fastly::fastly_host_error err;
+  fastly::fastly_world_string ret;
+  auto default_size = 128;
+  ret.ptr = static_cast<uint8_t *>(cabi_malloc(default_size, 4));
+  auto status = fastly::req_downstream_client_oh_fingerprint(ret.ptr, default_size, &ret.len);
+  if (status == FASTLY_HOST_ERROR_BUFFER_LEN) {
+    ret.ptr = static_cast<uint8_t *>(cabi_realloc(ret.ptr, default_size, 4, ret.len));
+    status = fastly::req_downstream_client_oh_fingerprint(ret.ptr, ret.len, &ret.len);
+  }
+  if (!convert_result(status, &err)) {
+    cabi_free(ret.ptr);
+    if (error_is_optional_none(err)) {
+      res.emplace(std::nullopt);
+    } else {
+      res.emplace_err(err);
+    }
+  } else {
+    res.emplace(make_host_string(ret));
+  }
+
+  return res;
+}
+
 bool HttpReq::is_valid() const { return this->handle != HttpReq::invalid; }
 
 Result<HttpVersion> HttpReq::get_version() const {

runtime/fastly/host-api/host_api_fastly.h

@@ -573,6 +573,12 @@ class HttpReq final : public HttpBase {
 
   static Result<std::optional<HostBytes>> http_req_downstream_tls_ja3_md5();
 
+  static Result<std::optional<HostString>> http_req_downstream_tls_ja4();
+
+  static Result<std::optional<HostString>> http_req_downstream_client_h2_fingerprint();
+
+  static Result<std::optional<HostString>> http_req_downstream_client_oh_fingerprint();
+
   Result<Void> auto_decompress_gzip();
 
   /// Send this request synchronously, and wait for the response.

types/globals.d.ts

@@ -436,6 +436,9 @@ declare interface ClientInfo {
   readonly address: string;
   readonly geo: import('fastly:geolocation').Geolocation | null;
   readonly tlsJA3MD5: string | null;
+  readonly tlsJA4: string | null;
+  readonly h2Fingerprint: string | null;
+  readonly ohFingerprint: string | null;
   readonly tlsCipherOpensslName: string | null;
   readonly tlsProtocol: string | null;
   readonly tlsClientCertificate: ArrayBuffer | null;