@prosopo/provider 4.11.6 → 4.13.0

package/dist/cjs/api/forwardVerify.cjs

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const api = require("@prosopo/api");
+const loadBalancer = require("@prosopo/load-balancer");
+function normalizeProviderUrl(url) {
+  try {
+    const parsed = new URL(url);
+    parsed.hostname = parsed.hostname.replace(/^(ipv4|ipv6)\./, "");
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return url.replace(/\/$/, "");
+  }
+}
+async function forwardVerifyIfNotIssuer(args) {
+  const { env, logger, path, providerUrl, dapp, user, body, alreadyForwarded } = args;
+  if (alreadyForwarded) {
+    return null;
+  }
+  if (!providerUrl) {
+    return null;
+  }
+  let providers;
+  try {
+    providers = await loadBalancer.getProviders(env.defaultEnvironment);
+  } catch (error) {
+    logger.warn(() => ({
+      msg: "Failed to load provider list; verifying locally",
+      err: error instanceof Error ? error : new Error(String(error)),
+      data: { providerUrl }
+    }));
+    return null;
+  }
+  const normalizedProviderUrl = normalizeProviderUrl(providerUrl);
+  const issuer = providers.find(
+    (provider) => normalizeProviderUrl(provider.url) === normalizedProviderUrl
+  );
+  if (!issuer) {
+    logger.warn(() => ({
+      msg: "Token providerUrl is not a known provider; verifying locally",
+      data: { providerUrl }
+    }));
+    return null;
+  }
+  if (env.pair?.address && issuer.address === env.pair.address) {
+    return null;
+  }
+  logger.info(() => ({
+    msg: "Forwarding verify request to issuing provider",
+    data: { providerUrl, path, dapp }
+  }));
+  const providerApi = new api.ProviderApi(issuer.url, dapp);
+  return providerApi.forwardVerify(path, body, user);
+}
+exports.forwardVerifyIfNotIssuer = forwardVerifyIfNotIssuer;

package/dist/cjs/api/headerCheckMiddleware.cjs

@@ -19,10 +19,13 @@ const headerCheckMiddleware = (env) => {
       validateAddress.validateAddr(user, void 0, req.logger);
       req.user = user;
       req.siteKey = siteKey;
-      req.logger = req.logger.with({
-        user,
-        siteKey
-      });
+      req.logger = req.logger.with(
+        {
+          user,
+          siteKey
+        },
+        "header-check"
+      );
       next();
     } catch (err) {
       return apiExpressRouter.handleErrors(err, req, res, next);

package/dist/cjs/api/ja4.cjs

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const node_crypto = require("node:crypto");
+const RECORD_HEADER_LENGTH = 5;
+const HANDSHAKE_HEADER_LENGTH = 4;
+const HANDSHAKE_RECORD_TYPE = 22;
+const HANDSHAKE_MESSAGE_TYPE = 1;
+const EXT_SERVER_NAME = 0;
+const EXT_SIGNATURE_ALGORITHMS = 13;
+const EXT_ALPN = 16;
+const EXT_SUPPORTED_VERSIONS = 43;
+function isGrease(id) {
+  return (id & 3855) === 2570 && id >> 8 === (id & 255);
+}
+function hash12(input) {
+  return node_crypto.createHash("sha256").update(input).digest("hex").slice(0, 12);
+}
+function formatIdList(ids) {
+  return ids.map((id) => id.toString(16).padStart(4, "0")).join(",");
+}
+function alpnChar(b) {
+  if (b >= 48 && b <= 57 || // 0-9
+  b >= 65 && b <= 90 || // A-Z
+  b >= 97 && b <= 122) {
+    return String.fromCharCode(b);
+  }
+  return b.toString(16).padStart(2, "0");
+}
+function alpnFirstLast(protocol) {
+  const first = protocol.length > 0 ? alpnChar(protocol.readUInt8(0)) : "0";
+  const last = protocol.length > 1 ? alpnChar(protocol.readUInt8(protocol.length - 1)) : "0";
+  return [first, last];
+}
+function tlsVersionStr(version) {
+  switch (version) {
+    case 769:
+      return "10";
+    case 770:
+      return "11";
+    case 771:
+      return "12";
+    case 772:
+      return "13";
+    default:
+      return "00";
+  }
+}
+class Ja4ParseError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "Ja4ParseError";
+  }
+}
+function calculateJa4(data) {
+  let offset = 0;
+  if (data.length < RECORD_HEADER_LENGTH + HANDSHAKE_HEADER_LENGTH) {
+    throw new Ja4ParseError("ClientHello too short");
+  }
+  const recordType = data.readUInt8(offset);
+  offset += 1;
+  if (recordType !== HANDSHAKE_RECORD_TYPE) {
+    throw new Ja4ParseError(
+      `Invalid record type: 0x${recordType.toString(16)}`
+    );
+  }
+  offset += 2;
+  const recordLen = data.readUInt16BE(offset);
+  offset += 2;
+  if (data.length < RECORD_HEADER_LENGTH + recordLen) {
+    throw new Ja4ParseError("Record length exceeds buffer");
+  }
+  data = data.subarray(0, RECORD_HEADER_LENGTH + recordLen);
+  if (data.length < RECORD_HEADER_LENGTH + HANDSHAKE_HEADER_LENGTH) {
+    throw new Ja4ParseError("Record too short for handshake header");
+  }
+  const msgType = data.readUInt8(offset);
+  offset += 1;
+  if (msgType !== HANDSHAKE_MESSAGE_TYPE) {
+    throw new Ja4ParseError(
+      `Not a ClientHello: handshake type 0x${msgType.toString(16)}`
+    );
+  }
+  const msgLen = data.readUIntBE(offset, 3);
+  offset += 3;
+  if (data.length - offset < msgLen) {
+    throw new Ja4ParseError("Handshake message length exceeds record");
+  }
+  data = data.subarray(0, offset + msgLen);
+  if (data.length - offset < 35) {
+    throw new Ja4ParseError("ClientHello body too short");
+  }
+  let clientVersion = data.readUInt16BE(offset);
+  offset += 2;
+  offset += 32;
+  const sessionIdLen = data.readUInt8(offset);
+  offset += 1;
+  if (data.length - offset < sessionIdLen) {
+    throw new Ja4ParseError("Truncated at session ID");
+  }
+  offset += sessionIdLen;
+  if (data.length - offset < 2) {
+    throw new Ja4ParseError("Truncated at cipher suites length");
+  }
+  const cipherSuitesLen = data.readUInt16BE(offset);
+  offset += 2;
+  if (data.length - offset < cipherSuitesLen) {
+    throw new Ja4ParseError("Truncated at cipher suites");
+  }
+  if (cipherSuitesLen % 2 !== 0) {
+    throw new Ja4ParseError("Cipher suites length is not a multiple of 2");
+  }
+  const cipherSuites = [];
+  for (let i = 0; i < cipherSuitesLen; i += 2) {
+    cipherSuites.push(data.readUInt16BE(offset + i));
+  }
+  offset += cipherSuitesLen;
+  if (data.length - offset < 1) {
+    throw new Ja4ParseError("Truncated at compression methods");
+  }
+  const compressionLen = data.readUInt8(offset);
+  offset += 1;
+  if (data.length - offset < compressionLen) {
+    throw new Ja4ParseError("Truncated at compression methods data");
+  }
+  offset += compressionLen;
+  if (data.length - offset < 2) {
+    throw new Ja4ParseError("Truncated at extensions length");
+  }
+  const extensionsLen = data.readUInt16BE(offset);
+  offset += 2;
+  if (data.length - offset < extensionsLen) {
+    throw new Ja4ParseError("Truncated at extensions");
+  }
+  const extIds = [];
+  const sigAlgorithms = [];
+  const alpnProtocols = [];
+  let extOffset = offset;
+  const extEnd = offset + extensionsLen;
+  while (extOffset + 4 <= extEnd) {
+    const extId = data.readUInt16BE(extOffset);
+    extOffset += 2;
+    const extLen = data.readUInt16BE(extOffset);
+    extOffset += 2;
+    if (extOffset + extLen > extEnd) break;
+    const extData = data.subarray(extOffset, extOffset + extLen);
+    extOffset += extLen;
+    extIds.push(extId);
+    if (extId === EXT_SUPPORTED_VERSIONS) {
+      if (extData.length >= 1) {
+        const listLen = extData.readUInt8(0);
+        let best = 0;
+        for (let i = 1; i + 1 < extData.length && i + 1 <= listLen; i += 2) {
+          const v = extData.readUInt16BE(i);
+          if (!isGrease(v) && v > best) best = v;
+        }
+        if (best > 0) clientVersion = best;
+      }
+    } else if (extId === EXT_SIGNATURE_ALGORITHMS) {
+      if (extData.length >= 2) {
+        const algLen = extData.readUInt16BE(0);
+        for (let i = 2; i + 1 < extData.length && i + 1 < algLen + 2; i += 2) {
+          const alg = extData.readUInt16BE(i);
+          if (!isGrease(alg)) sigAlgorithms.push(alg);
+        }
+      }
+    } else if (extId === EXT_ALPN) {
+      if (extData.length >= 2) {
+        const listLen = extData.readUInt16BE(0);
+        const listEnd = Math.min(extData.length, 2 + listLen);
+        let alpnOff = 2;
+        while (alpnOff < listEnd) {
+          const protoLen = extData.readUInt8(alpnOff);
+          alpnOff += 1;
+          if (alpnOff + protoLen > listEnd) break;
+          alpnProtocols.push(extData.subarray(alpnOff, alpnOff + protoLen));
+          alpnOff += protoLen;
+        }
+      }
+    }
+  }
+  const versionStr = tlsVersionStr(clientVersion);
+  const sni = extIds.includes(EXT_SERVER_NAME) ? "d" : "i";
+  const firstAlpn = alpnProtocols[0];
+  const [alpnFirst, alpnLast] = firstAlpn ? alpnFirstLast(firstAlpn) : ["0", "0"];
+  const nonGreaseCiphers = cipherSuites.filter((c) => !isGrease(c));
+  const nonGreaseExts = extIds.filter((e) => !isGrease(e));
+  const cipherCount = Math.min(99, nonGreaseCiphers.length).toString().padStart(2, "0");
+  const extCount = Math.min(99, nonGreaseExts.length).toString().padStart(2, "0");
+  const firstChunk = `t${versionStr}${sni}${cipherCount}${extCount}${alpnFirst}${alpnLast}`;
+  const sortedCiphers = [...nonGreaseCiphers].sort((a, b) => a - b);
+  const cipherHash = hash12(formatIdList(sortedCiphers));
+  const filteredExts = nonGreaseExts.filter(
+    (e) => e !== EXT_SERVER_NAME && e !== EXT_ALPN
+  );
+  const sortedExts = [...filteredExts].sort((a, b) => a - b);
+  const extStr = formatIdList(sortedExts);
+  const sigAlgStr = formatIdList(sigAlgorithms);
+  const extHashInput = sigAlgStr.length > 0 ? `${extStr}_${sigAlgStr}` : extStr;
+  const extHash = hash12(extHashInput);
+  return `${firstChunk}_${cipherHash}_${extHash}`;
+}
+exports.Ja4ParseError = Ja4ParseError;
+exports.calculateJa4 = calculateJa4;

package/dist/cjs/api/ja4Middleware.cjs

@@ -1,14 +1,12 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const node_stream = require("node:stream");
 const apiExpressRouter = require("@prosopo/api-express-router");
 const logger = require("@prosopo/logger");
 const utilCrypto = require("@prosopo/util-crypto");
-const readTlsClientHello = require("read-tls-client-hello");
-var _documentCurrentScript = typeof document !== "undefined" ? document.currentScript : null;
+const ja4 = require("./ja4.cjs");
 const DEFAULT_JA4 = "ja4";
 const getJA4 = async (headers, logger$1) => {
-  logger$1 = logger$1 || logger.getLogger("info", typeof document === "undefined" ? require("url").pathToFileURL(__filename).href : _documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === "SCRIPT" && _documentCurrentScript.src || new URL("api/ja4Middleware.cjs", document.baseURI).href);
+  logger$1 = logger$1 || logger.getLogger("info", "provider:ja4");
   if (process.env.NODE_ENV === "development") {
     return {
       ja4PlusFingerprint: `${DEFAULT_JA4}${utilCrypto.randomAsHex().slice(28, 32)}`
@@ -16,7 +14,6 @@ const getJA4 = async (headers, logger$1) => {
   }
   try {
     const xTlsClientHello = (headers["x-tls-clienthello"] || "").toString();
-    const xTlsVersion = (headers["x-tls-version"] || "").toString().toLowerCase();
     const clientHelloBuffer = Buffer.from(xTlsClientHello, "base64");
     logger$1.debug(() => ({
       msg: "ClientHello First Bytes:",
@@ -28,17 +25,7 @@ const getJA4 = async (headers, logger$1) => {
       }));
       return { ja4PlusFingerprint: DEFAULT_JA4 };
     }
-    logger$1.debug(() => ({
-      msg: "Headers TLS Version:",
-      data: { xTlsVersion }
-    }));
-    const readableStream = new node_stream.Readable({
-      read() {
-        this.push(clientHelloBuffer);
-      }
-    });
-    const clientHello = await readTlsClientHello.readTlsClientHello(readableStream);
-    const ja4PlusFingerprint = readTlsClientHello.calculateJa4FromHelloData(clientHello);
+    const ja4PlusFingerprint = ja4.calculateJa4(clientHelloBuffer);
     return { ja4PlusFingerprint };
   } catch (e) {
     logger$1.error(() => ({
@@ -52,11 +39,14 @@ const ja4Middleware = (env) => {
   return async (req, res, next) => {
     try {
       req.logger.debug(() => ({ data: { url: req.url } }));
-      const ja4 = await getJA4(req.headers, req.logger);
-      req.ja4 = ja4.ja4PlusFingerprint || "";
-      req.logger = req.logger.with({
-        ja4: req.ja4
-      });
+      const ja42 = await getJA4(req.headers, req.logger);
+      req.ja4 = ja42.ja4PlusFingerprint || "";
+      req.logger = req.logger.with(
+        {
+          ja4: req.ja4
+        },
+        "ja4"
+      );
       next();
     } catch (err) {
       return apiExpressRouter.handleErrors(err, req, res, next);

package/dist/cjs/api/metrics.cjs

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const types = require("@prosopo/types");
+const promClient = require("prom-client");
+const metricsEnabled = () => process.env.PROSOPO_METRICS_ENABLED !== "false";
+const PREFIX = "prosopo_";
+const LATENCY_BUCKETS = [
+  5e-3,
+  0.01,
+  0.025,
+  0.05,
+  0.1,
+  0.25,
+  0.5,
+  1,
+  2.5,
+  5,
+  10
+];
+const SCORE_BUCKETS = [
+  0,
+  0.1,
+  0.2,
+  0.3,
+  0.4,
+  0.5,
+  0.6,
+  0.7,
+  0.8,
+  0.9,
+  1,
+  1.5,
+  2,
+  3,
+  5,
+  10
+];
+const KNOWN_ROUTES = /* @__PURE__ */ new Set([
+  ...Object.values(types.ClientApiPaths),
+  ...Object.values(types.PublicApiPaths),
+  ...Object.values(types.AdminApiPaths)
+]);
+const normaliseRoute = (req) => {
+  const path = req.path;
+  return KNOWN_ROUTES.has(path) ? path : "other";
+};
+let metrics;
+const buildMetrics = () => {
+  const registry = new promClient.Registry();
+  promClient.collectDefaultMetrics({ register: registry, prefix: PREFIX });
+  const httpRequestsTotal = new promClient.Counter({
+    name: `${PREFIX}http_requests_total`,
+    help: "Total HTTP requests handled by the provider API",
+    labelNames: ["route", "method", "status"],
+    registers: [registry]
+  });
+  const httpRequestDuration = new promClient.Histogram({
+    name: `${PREFIX}http_request_duration_seconds`,
+    help: "Provider API request duration in seconds",
+    labelNames: ["route", "method", "status"],
+    buckets: LATENCY_BUCKETS,
+    registers: [registry]
+  });
+  const captchaIssuedTotal = new promClient.Counter({
+    name: `${PREFIX}captcha_issued_total`,
+    help: "Captcha challenges issued, by type",
+    labelNames: ["type"],
+    registers: [registry]
+  });
+  const captchaIssueErrorsTotal = new promClient.Counter({
+    name: `${PREFIX}captcha_issue_errors_total`,
+    help: "Errors while issuing captcha challenges, by type",
+    labelNames: ["type"],
+    registers: [registry]
+  });
+  const captchaVerifyTotal = new promClient.Counter({
+    name: `${PREFIX}captcha_verify_total`,
+    help: "Captcha verification outcomes, by type/result/source",
+    labelNames: ["type", "result", "source"],
+    registers: [registry]
+  });
+  const frictionlessRoutedTotal = new promClient.Counter({
+    name: `${PREFIX}frictionless_routed_total`,
+    help: "Frictionless routing decisions (which captcha the user was sent to)",
+    labelNames: ["decision"],
+    registers: [registry]
+  });
+  const botScore = new promClient.Histogram({
+    name: `${PREFIX}bot_score`,
+    help: "Distribution of frictionless bot scores (0=human .. 1=bot; language-rule penalties can push it above 1)",
+    buckets: SCORE_BUCKETS,
+    registers: [registry]
+  });
+  const detectorTriggeredTotal = new promClient.Counter({
+    name: `${PREFIX}detector_triggered_total`,
+    help: "Count of times each bot detector was triggered",
+    labelNames: ["detector"],
+    registers: [registry]
+  });
+  const blockedRequestsTotal = new promClient.Counter({
+    name: `${PREFIX}blocked_requests_total`,
+    help: "Requests blocked before reaching a captcha handler, by reason",
+    labelNames: ["reason"],
+    registers: [registry]
+  });
+  const domainValidationTotal = new promClient.Counter({
+    name: `${PREFIX}domain_validation_total`,
+    help: "Domain/site-key validation outcomes",
+    labelNames: ["result"],
+    registers: [registry]
+  });
+  const spamEmailTotal = new promClient.Counter({
+    name: `${PREFIX}spam_email_total`,
+    help: "Spam email-domain check outcomes",
+    labelNames: ["result"],
+    registers: [registry]
+  });
+  const maintenanceMode = new promClient.Gauge({
+    name: `${PREFIX}maintenance_mode`,
+    help: "1 when the provider is in maintenance mode, else 0",
+    registers: [registry]
+  });
+  maintenanceMode.set(
+    process.env.MAINTENANCE_MODE?.toLowerCase() === "true" ? 1 : 0
+  );
+  const redisReady = new promClient.Gauge({
+    name: `${PREFIX}redis_ready`,
+    help: "1 when the given redis connection is ready, else 0",
+    labelNames: ["actor"],
+    registers: [registry]
+  });
+  return {
+    registry,
+    httpRequestsTotal,
+    httpRequestDuration,
+    captchaIssuedTotal,
+    captchaIssueErrorsTotal,
+    captchaVerifyTotal,
+    frictionlessRoutedTotal,
+    botScore,
+    detectorTriggeredTotal,
+    blockedRequestsTotal,
+    domainValidationTotal,
+    spamEmailTotal,
+    maintenanceMode,
+    redisReady
+  };
+};
+const getMetrics = () => {
+  if (!metrics) {
+    metrics = buildMetrics();
+  }
+  return metrics;
+};
+const recordCaptchaIssued = (type) => {
+  if (!metricsEnabled()) return;
+  getMetrics().captchaIssuedTotal.inc({ type });
+};
+const recordCaptchaIssueError = (type) => {
+  if (!metricsEnabled()) return;
+  getMetrics().captchaIssueErrorsTotal.inc({ type });
+};
+const recordCaptchaVerify = (args) => {
+  if (!metricsEnabled()) return;
+  getMetrics().captchaVerifyTotal.inc({
+    type: args.type,
+    result: args.verified ? "verified" : "failed",
+    source: args.source
+  });
+};
+const recordFrictionlessDecision = (decision) => {
+  if (!metricsEnabled()) return;
+  getMetrics().frictionlessRoutedTotal.inc({ decision });
+};
+const recordBotScore = (score) => {
+  if (!metricsEnabled()) return;
+  getMetrics().botScore.observe(score);
+};
+const recordDetectorTriggered = (detectors) => {
+  if (!metricsEnabled()) return;
+  const m = getMetrics();
+  for (const detector of detectors) {
+    m.detectorTriggeredTotal.inc({ detector: String(detector) });
+  }
+};
+const recordBlockedRequest = (reason) => {
+  if (!metricsEnabled()) return;
+  getMetrics().blockedRequestsTotal.inc({ reason });
+};
+const recordDomainValidation = (result) => {
+  if (!metricsEnabled()) return;
+  getMetrics().domainValidationTotal.inc({ result });
+};
+const recordSpamEmail = (result) => {
+  if (!metricsEnabled()) return;
+  getMetrics().spamEmailTotal.inc({ result });
+};
+const setMaintenanceModeGauge = (on) => {
+  if (!metricsEnabled()) return;
+  getMetrics().maintenanceMode.set(on ? 1 : 0);
+};
+const metricsMiddleware = () => {
+  return (req, res, next) => {
+    if (!metricsEnabled()) return next();
+    const start = process.hrtime.bigint();
+    res.on("finish", () => {
+      const route = normaliseRoute(req);
+      const labels = {
+        route,
+        method: req.method,
+        status: String(res.statusCode)
+      };
+      const durationSeconds = Number(process.hrtime.bigint() - start) / 1e9;
+      const m = getMetrics();
+      m.httpRequestsTotal.inc(labels);
+      m.httpRequestDuration.observe(labels, durationSeconds);
+    });
+    next();
+  };
+};
+const metricsHandler = (env) => {
+  return async (req, res) => {
+    const token = process.env.PROSOPO_METRICS_TOKEN;
+    if (token && req.headers.authorization !== `Bearer ${token}`) {
+      res.status(401).send("Unauthorized");
+      return;
+    }
+    const m = getMetrics();
+    try {
+      const db = env.getDb();
+      m.redisReady.set(
+        { actor: "general" },
+        db.getRedisConnection().isReady() ? 1 : 0
+      );
+      m.redisReady.set(
+        { actor: "uap" },
+        db.getRedisAccessRulesConnection().isReady() ? 1 : 0
+      );
+    } catch {
+      m.redisReady.set({ actor: "general" }, 0);
+      m.redisReady.set({ actor: "uap" }, 0);
+    }
+    res.set("Content-Type", m.registry.contentType);
+    res.end(await m.registry.metrics());
+  };
+};
+exports.getMetrics = getMetrics;
+exports.metricsEnabled = metricsEnabled;
+exports.metricsHandler = metricsHandler;
+exports.metricsMiddleware = metricsMiddleware;
+exports.recordBlockedRequest = recordBlockedRequest;
+exports.recordBotScore = recordBotScore;
+exports.recordCaptchaIssueError = recordCaptchaIssueError;
+exports.recordCaptchaIssued = recordCaptchaIssued;
+exports.recordCaptchaVerify = recordCaptchaVerify;
+exports.recordDetectorTriggered = recordDetectorTriggered;
+exports.recordDomainValidation = recordDomainValidation;
+exports.recordFrictionlessDecision = recordFrictionlessDecision;
+exports.recordSpamEmail = recordSpamEmail;
+exports.setMaintenanceModeGauge = setMaintenanceModeGauge;

package/dist/cjs/api/public.cjs

@@ -5,11 +5,16 @@ const common = require("@prosopo/common");
 const types = require("@prosopo/types");
 const util = require("@prosopo/util");
 const express = require("express");
+const metrics = require("./metrics.cjs");
 function publicRouter(env) {
   const router = express.Router();
   router.get(types.PublicApiPaths.Healthz, (req, res) => {
-    res.status(200).send("OK");
+    const host = env.config.host && env.config.host.length > 0 ? env.config.host : req.hostname;
+    return res.status(200).json({ ok: true, host });
   });
+  if (metrics.metricsEnabled()) {
+    router.get(types.PublicApiPaths.Metrics, metrics.metricsHandler(env));
+  }
   router.get(types.PublicApiPaths.GetProviderDetails, async (req, res, next) => {
     try {
       const db = env.getDb();