@paywalls-net/filter 1.3.9 → 1.3.10

package/jest.config.js

@@ -0,0 +1,7 @@
+export default {
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.js'],
+  // ESM transform: jest uses --experimental-vm-modules via the npm script
+  transform: {},
+};

package/package.json

@@ -3,7 +3,7 @@
   "description": "Client SDK for integrating paywalls.net bot filtering and authorization services into your server or CDN.",
   "author": "paywalls.net",
   "license": "MIT",
-  "version": "1.3.9",
+  "version": "1.3.10",
   "publishConfig": {
     "access": "public"
   },
@@ -17,9 +17,13 @@
     ".": "./src/index.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --runInBand",
+    "test:watch": "node --experimental-vm-modules node_modules/.bin/jest --watch"
   },
   "dependencies": {
     "ua-parser-js": "^2.0.4"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
   }
 }

package/src/index.js

@@ -4,6 +4,11 @@
  */
 const sdk_version = "1.2.x";
 import { classifyUserAgent, loadAgentPatterns } from './user-agent-classification.js';
+import {
+    extractAcceptFeatures, extractEncodingFeatures, extractLanguageFeatures,
+    extractNetFeatures, extractCHFeatures, extractUAFeatures,
+    computeUAHMAC, computeConfidenceToken,
+} from './signal-extraction.js';
 
 const PAYWALLS_CLOUD_API_HOST = "https://cloud-api.paywalls.net";
 
@@ -91,27 +96,12 @@ const PROXY_HEADER_MAP = [
 ];
 
 /**
- * Maps browser signal sources → X-PW-* forwarding headers (§5.2).
- * Each entry: { from: 'headers'|'cf', src: string, dest: string }
- *   from:'headers' — read from incoming request headers (lowercase)
- *   from:'cf'      — read from request.cf property
+ * Set a header only if the value is non-null (extractor returns null for
+ * absent inputs → header omitted entirely, not sent as empty string).
  */
-const SIGNAL_HEADER_MAP = [
-    // Bundle A: Sec-Fetch (3 pts)
-    { from: 'headers', src: 'sec-fetch-dest',  dest: 'X-PW-Sec-Fetch-Dest'  },
-    { from: 'headers', src: 'sec-fetch-mode',  dest: 'X-PW-Sec-Fetch-Mode'  },
-    { from: 'headers', src: 'sec-fetch-site',  dest: 'X-PW-Sec-Fetch-Site'  },
-    // Bundle B: Accept (2 pts)
-    { from: 'headers', src: 'accept',          dest: 'X-PW-Accept'          },
-    { from: 'headers', src: 'accept-language', dest: 'X-PW-Accept-Language' },
-    { from: 'headers', src: 'accept-encoding', dest: 'X-PW-Accept-Encoding' },
-    // Bundle C: Client Hints (2 pts)
-    { from: 'headers', src: 'sec-ch-ua',       dest: 'X-PW-Sec-CH-UA'       },
-    // Bundle D: CF infrastructure (1 pt) — only valid at first-hop CF Worker
-    { from: 'cf',      src: 'tlsVersion',      dest: 'X-PW-TLS-Version'     },
-    { from: 'cf',      src: 'httpProtocol',    dest: 'X-PW-HTTP-Protocol'   },
-    { from: 'cf',      src: 'asn',             dest: 'X-PW-ASN'             },
-];
+function setIfPresent(obj, key, value) {
+    if (value != null) obj[key] = value;
+}
 
 /**
  * Proxy VAI requests to the cloud-api service (Spec §7).
@@ -128,10 +118,9 @@ const SIGNAL_HEADER_MAP = [
  *  - User-Agent, X-Forwarded-For: standard proxy headers
  *  - Authorization: publisher API key (§7.4)
  * 
- * Human-confidence signal forwarding (§5.2):
- *  Driven by SIGNAL_HEADER_MAP — each entry specifies a source ('headers' or 'cf')
- *  and property name to read, and the X-PW-* destination header to write.
- *  Simple passthrough: present values forwarded, absent values omitted.
+ * Human-confidence signal forwarding (§7.2):
+ *  Uses signal-extraction module to transform raw browser headers into compact
+ *  RFC 8941 Structured Field Value strings.  Absent inputs → null → header omitted.
  * 
  * Response passthrough (§7.3):
  *  All response headers from cloud-api are returned unchanged — including
@@ -155,7 +144,7 @@ async function proxyVAIRequest(cfg, request) {
         // Build forwarding headers — include everything cloud-api needs
         // for CORS evaluation, domain auth, and request context.
         const forwardHeaders = {
-            'User-Agent': headers['user-agent'] || sdkUserAgent,
+            'User-Agent': sdkUserAgent,
             'Authorization': `Bearer ${cfg.paywallsAPIKey}`
         };
         
@@ -171,16 +160,29 @@ async function proxyVAIRequest(cfg, request) {
             if (headers[src]) forwardHeaders[dest] = headers[src];
         }
 
-        // Forward browser-provenance signals as X-PW-* headers (§5.2).
-        // Simple passthrough: forward whatever is present, no cross-request state.
+        // Signal protocol version (§7.1)
+        forwardHeaders['X-PW-V'] = '2';
+
         const cf = request.cf || {};
-        const sources = { headers, cf };
-        for (const { from, src, dest } of SIGNAL_HEADER_MAP) {
-            const value = sources[from][src];
-            if (value != null && value !== '') {
-                forwardHeaders[dest] = String(value);
-            }
-        }
+
+        // Tier 1: kept raw (§6.1)
+        setIfPresent(forwardHeaders, 'X-PW-Sec-Fetch-Dest', headers['sec-fetch-dest']);
+        setIfPresent(forwardHeaders, 'X-PW-Sec-Fetch-Mode', headers['sec-fetch-mode']);
+        setIfPresent(forwardHeaders, 'X-PW-Sec-Fetch-Site', headers['sec-fetch-site']);
+        setIfPresent(forwardHeaders, 'X-PW-TLS-Version',    cf.tlsVersion != null ? String(cf.tlsVersion) : null);
+        setIfPresent(forwardHeaders, 'X-PW-HTTP-Protocol',  cf.httpProtocol != null ? String(cf.httpProtocol) : null);
+
+        // Tier 2: extract features (§6.2)
+        setIfPresent(forwardHeaders, 'X-PW-Accept', extractAcceptFeatures(headers['accept']));
+        setIfPresent(forwardHeaders, 'X-PW-Enc',    extractEncodingFeatures(headers['accept-encoding']));
+        setIfPresent(forwardHeaders, 'X-PW-Lang',   extractLanguageFeatures(headers['accept-language']));
+        setIfPresent(forwardHeaders, 'X-PW-Net',    extractNetFeatures(cf.asn));
+        setIfPresent(forwardHeaders, 'X-PW-CH',     extractCHFeatures(headers['sec-ch-ua'], headers['user-agent']));
+
+        // Tier 3: UA features + HMAC (§6.3)
+        setIfPresent(forwardHeaders, 'X-PW-UA', extractUAFeatures(headers['user-agent']));
+        setIfPresent(forwardHeaders, 'X-PW-UA-HMAC', await computeUAHMAC(headers['user-agent'], cfg.vaiUAHmacKey));
+        setIfPresent(forwardHeaders, 'X-PW-CT-FP',   await computeConfidenceToken(headers['user-agent'], headers['accept-language'], headers['sec-ch-ua']));
 
         // Forward request to cloud-api
         const response = await fetch(`${cfg.paywallsAPIHost}${cloudApiPath}`, {
@@ -417,7 +419,8 @@ async function cloudflare(config = null) {
             paywallsAPIHost: env.PAYWALLS_CLOUD_API_HOST || PAYWALLS_CLOUD_API_HOST,
             paywallsAPIKey: env.PAYWALLS_CLOUD_API_KEY,
             paywallsPublisherId: env.PAYWALLS_PUBLISHER_ID,
-            vaiPath: env.PAYWALLS_VAI_PATH || '/pw'
+            vaiPath: env.PAYWALLS_VAI_PATH || '/pw',
+            vaiUAHmacKey: env.VAI_UA_HMAC_KEY || null,
         };
         
         // Check if this is a VAI endpoint request and proxy it
@@ -449,7 +452,8 @@ async function fastly() {
             paywallsAPIHost: config.get('PAYWALLS_CLOUD_API_HOST') || PAYWALLS_CLOUD_API_HOST,
             paywallsAPIKey: config.get('PAYWALLS_API_KEY'),
             paywallsPublisherId: config.get('PAYWALLS_PUBLISHER_ID'),
-            vaiPath: config.get('PAYWALLS_VAI_PATH') || '/pw'
+            vaiPath: config.get('PAYWALLS_VAI_PATH') || '/pw',
+            vaiUAHmacKey: config.get('VAI_UA_HMAC_KEY') || null,
         };
         
         // Check if this is a VAI endpoint request and proxy it
@@ -531,7 +535,8 @@ async function cloudfront(config) {
         paywallsAPIHost: config.PAYWALLS_CLOUD_API_HOST || PAYWALLS_CLOUD_API_HOST,
         paywallsAPIKey: config.PAYWALLS_API_KEY,
         paywallsPublisherId: config.PAYWALLS_PUBLISHER_ID,
-        vaiPath: config.PAYWALLS_VAI_PATH || '/pw'
+        vaiPath: config.PAYWALLS_VAI_PATH || '/pw',
+        vaiUAHmacKey: config.VAI_UA_HMAC_KEY || null,
     };
     await loadAgentPatterns(paywallsConfig);
 

package/src/signal-extraction.js

@@ -0,0 +1,385 @@
+/**
+ * Signal Extraction Module — Tier 2 + Tier 3 feature extractors
+ *
+ * Transforms raw browser headers into compact RFC 8941 Structured Field
+ * Dictionary strings for privacy-preserving VAI signal forwarding.
+ *
+ * Spec: specs/vai-privacy-v2.spec.md §6.2–§6.4
+ *
+ * Each function returns an SF-Dictionary string (e.g. "html, wildcard")
+ * or null if the input is absent/empty.  null means the caller should
+ * omit the header entirely (not send an empty value).
+ */
+
+// ── §6.2.4 / Appendix A: Data-center ASN set ──────────────────────────────
+// Comprehensive cloud/hosting provider ASNs for DC classification.
+// Kept in sync with cloud-api DC_ASN_LIST (cloudflare/vai.js).
+// Source: public ASN registries (PeeringDB, RIPE, ARIN).
+const DC_ASN_SET = new Set([
+  // ── Major IaaS ───────────────────────────────────────────────────────────
+  16509, 14618,          // Amazon AWS (primary + secondary)
+  396982, 36492, 15169,  // Google Cloud + Google infra
+  8075, 8069, 8068,      // Microsoft Azure
+  31898,                 // Oracle Cloud
+  36351,                 // IBM Cloud / SoftLayer
+  45102,                 // Alibaba Cloud
+  132203,                // Tencent Cloud
+
+  // ── VPS / Hosting ────────────────────────────────────────────────────────
+  14061,                 // DigitalOcean
+  24940, 213230,         // Hetzner (dedicated + cloud)
+  16276,                 // OVH
+  63949,                 // Linode / Akamai Connected Cloud
+  20473,                 // Vultr / The Constant Company
+  12876,                 // Scaleway
+  51167,                 // Contabo
+  60781, 28753,          // Leaseweb (NL + global)
+]);
+
+// ── §6.2.1  Accept → X-PW-Accept ──────────────────────────────────────────
+/**
+ * Extract boolean feature flags from the Accept header.
+ *
+ * @param {string|null|undefined} accept  Raw Accept header value
+ * @returns {string|null}  SF-Dictionary string or null if absent/empty
+ */
+export function extractAcceptFeatures(accept) {
+  if (!accept) return null;
+
+  const parts = [];
+  if (accept.includes('text/html'))          parts.push('html');
+  if (accept.includes('*/*'))                parts.push('wildcard');
+  if (accept.includes('application/json'))   parts.push('json');
+  if (accept.includes('image/'))             parts.push('image');
+
+  return parts.length > 0 ? parts.join(', ') : null;
+}
+
+// ── §6.2.2  Accept-Encoding → X-PW-Enc ────────────────────────────────────
+/**
+ * Extract boolean feature flags from the Accept-Encoding header.
+ *
+ * @param {string|null|undefined} acceptEncoding  Raw Accept-Encoding value
+ * @returns {string|null}  SF-Dictionary string or null if absent/empty
+ */
+export function extractEncodingFeatures(acceptEncoding) {
+  if (!acceptEncoding) return null;
+
+  const parts = [];
+  const hasBr   = acceptEncoding.includes('br');
+  const hasGzip = acceptEncoding.includes('gzip');
+
+  if (hasBr)   parts.push('br');
+  if (hasGzip) parts.push('gzip');
+  if (hasBr && hasGzip) parts.push('modern');
+
+  return parts.length > 0 ? parts.join(', ') : null;
+}
+
+// ── §6.2.3  Accept-Language → X-PW-Lang ───────────────────────────────────
+/**
+ * Extract presence, primary language family, and locale count from
+ * the Accept-Language header.
+ *
+ * @param {string|null|undefined} acceptLanguage  Raw Accept-Language value
+ * @returns {string|null}  SF-Dictionary string or null if absent/empty
+ */
+export function extractLanguageFeatures(acceptLanguage) {
+  if (!acceptLanguage) return null;
+
+  const trimmed = acceptLanguage.trim();
+  if (trimmed === '' || trimmed === '*') return null;
+
+  // Split on comma to count locales, ignoring quality values
+  const locales = trimmed.split(',').map(s => s.trim().split(';')[0].trim()).filter(Boolean);
+  const count = locales.length;
+  if (count === 0) return null;
+
+  // Primary language family = first 2 chars of first locale (lowercase)
+  const first = locales[0].toLowerCase();
+  const primary = first.length >= 2 ? first.slice(0, 2) : first;
+
+  const parts = ['present', `primary=${primary}`, `count=${count}`];
+  return parts.join(', ');
+}
+
+// ── §6.2.4  ASN → X-PW-Net ────────────────────────────────────────────────
+/**
+ * Classify an ASN into a named enum category.
+ *
+ * @param {string|number|null|undefined} asn  Numeric ASN value
+ * @returns {string|null}  SF-Dictionary string or null if absent/empty
+ */
+export function extractNetFeatures(asn) {
+  if (asn == null || asn === '') return null;
+
+  const num = typeof asn === 'number' ? asn : parseInt(asn, 10);
+  if (isNaN(num)) return null;
+
+  const category = DC_ASN_SET.has(num) ? 'cloud' : 'consumer';
+  return `asn=${category}`;
+}
+
+// ── §6.2.5  Sec-CH-UA → X-PW-CH ───────────────────────────────────────────
+
+/**
+ * Extract Chrome version from a Sec-CH-UA header value.
+ * Looks for "Chromium" or "Google Chrome" brand and returns the major version.
+ *
+ * @param {string} secChUA  Raw Sec-CH-UA header
+ * @returns {number|null}  Major Chrome version or null
+ */
+function extractChromeVersionFromCH(secChUA) {
+  // Sec-CH-UA format: "Brand";v="version", "Brand";v="version", ...
+  const match = secChUA.match(/"(?:Google Chrome|Chromium)";v="(\d+)"/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Extract Chrome version from a User-Agent string.
+ *
+ * @param {string} userAgent  Raw User-Agent string
+ * @returns {number|null}  Major Chrome version or null
+ */
+function extractChromeVersionFromUA(userAgent) {
+  // UA format: ...Chrome/134.0.0.0...
+  const match = userAgent.match(/Chrome\/(\d+)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Extract features from Sec-CH-UA header, cross-referenced with User-Agent
+ * for the consistency check.
+ *
+ * @param {string|null|undefined} secChUA    Raw Sec-CH-UA header value
+ * @param {string|null|undefined} userAgent  Raw User-Agent string (for consistency check)
+ * @returns {string|null}  SF-Dictionary string or null if CH absent/empty
+ */
+export function extractCHFeatures(secChUA, userAgent) {
+  if (!secChUA) return null;
+
+  const trimmed = secChUA.trim();
+  if (trimmed === '') return null;
+
+  const parts = ['present'];
+
+  // Count brand entries: each is a quoted string followed by ;v="..."
+  // Split on comma to count entries
+  const brands = trimmed.split(',').map(s => s.trim()).filter(Boolean);
+  parts.push(`brands=${brands.length}`);
+
+  // GREASE detection: Chromium convention includes a "Not" brand
+  const hasGrease = brands.some(b => /not[^"]*brand/i.test(b) || /not[:\-_.]/i.test(b));
+  if (hasGrease) parts.push('grease');
+
+  // Consistency check: Chrome version in CH matches Chrome version in UA
+  if (userAgent) {
+    const chVersion = extractChromeVersionFromCH(trimmed);
+    const uaVersion = extractChromeVersionFromUA(userAgent);
+    if (chVersion != null && uaVersion != null && chVersion === uaVersion) {
+      parts.push('consistent');
+    }
+  }
+
+  return parts.join(', ');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+//  Tier 3 — Replace User-Agent with derived features (§6.3) + CT (§6.4)
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ── §6.3.3  Automation marker detection ────────────────────────────────────
+// HeadlessChrome triggers 'headless' only (via HEADLESS_MARKERS).
+// Explicit automation tools (Puppeteer, Selenium, etc.) trigger 'automation'.
+const AUTOMATION_MARKERS = [
+  /Puppeteer/i, /Playwright/i, /Selenium/i, /WebDriver/i,
+  /PhantomJS/i, /CasperJS/i,
+  /python-requests/i, /python-urllib/i, /Go-http-client/i,
+  /okhttp/i, /Apache-HttpClient/i, /libcurl/i,
+  /\bcurl\//i, /\bwget\//i, /HTTPie/i,
+  /node-fetch/i, /undici/i, /axios\//i, /\bgot\//i, /superagent/i,
+  /Cypress/i, /TestCafe/i, /Nightwatch/i, /WebdriverIO/i,
+];
+
+const HEADLESS_MARKERS = [/HeadlessChrome/i, /\bHeadless\b/i];
+
+// ── §6.3.4  Entropy bucketing ──────────────────────────────────────────────
+/**
+ * Bucket a User-Agent string's structural complexity.
+ * @param {string} userAgent
+ * @returns {'low'|'medium'|'high'}
+ */
+function computeUAEntropy(userAgent) {
+  if (!userAgent || userAgent.length < 10) return 'low';
+
+  const hasUpper   = /[A-Z]/.test(userAgent);
+  const hasLower   = /[a-z]/.test(userAgent);
+  const hasDigit   = /\d/.test(userAgent);
+  const hasSpecial = /[\/\.;()\s,_\-]/.test(userAgent);
+  const classCount = [hasUpper, hasLower, hasDigit, hasSpecial].filter(Boolean).length;
+
+  const len = userAgent.length;
+  const hasParens = /\([^)]+\)/.test(userAgent);
+
+  // Typical browser UA: 60-250 chars, 4 char classes, has parens
+  if (classCount >= 4 && len >= 60 && len <= 250 && hasParens) return 'medium';
+  if (classCount >= 3 && len >= 40 && len <= 300) return 'medium';
+
+  // Very short, very long, or missing structure
+  if (len < 40 || len > 300 || classCount < 3) return 'low';
+
+  // Unusual: high-entropy random strings
+  const uniqueChars = new Set(userAgent).size;
+  if (uniqueChars / len > 0.7) return 'high';
+
+  return 'medium';
+}
+
+// ── §6.3.1  UA dpf/version parsing ─────────────────────────────────────────
+
+/** @returns {'desktop'|'mobile'|'tablet'|'server'|'unknown'} */
+function detectDevice(ua) {
+  if (/\b(iPad|Tablet|PlayBook|Silk|Kindle)\b/i.test(ua)) return 'tablet';
+  if (/\b(iPhone|iPod|Android.*Mobile|Mobile.*Android|webOS|BlackBerry|Opera Mini|IEMobile|Windows Phone)\b/i.test(ua)) return 'mobile';
+  if (/\b(Android)\b/i.test(ua) && !/Mobile/i.test(ua)) return 'tablet';
+  if (/\b(Macintosh|Windows NT|X11|Linux(?!.*Android))\b/i.test(ua)) return 'desktop';
+  if (/\b(Googlebot|bingbot|Baiduspider|YandexBot|DuckDuckBot)\b/i.test(ua)) return 'server';
+  return 'unknown';
+}
+
+/** @returns {'windows'|'mac'|'ios'|'android'|'linux'|'other'} */
+function detectPlatform(ua) {
+  if (/\b(iPhone|iPad|iPod)\b/i.test(ua))          return 'ios';
+  if (/\bAndroid\b/i.test(ua))                      return 'android';
+  if (/\bMacintosh\b/i.test(ua))                    return 'mac';
+  if (/\bWindows\b/i.test(ua))                      return 'windows';
+  if (/\bLinux\b/i.test(ua) || /\bX11\b/i.test(ua)) return 'linux';
+  return 'other';
+}
+
+/** @returns {'chrome'|'safari'|'firefox'|'edge'|'other'|'bot'} */
+function detectFamily(ua) {
+  if (/\b(Googlebot|bingbot|Baiduspider|YandexBot|DuckDuckBot|Slurp|ia_archiver)\b/i.test(ua)) return 'bot';
+  // Order matters: Edge before Chrome (Edge UA contains "Chrome")
+  if (/\bEdg(?:e|A)?\/\d/i.test(ua))  return 'edge';
+  if (/\bFirefox\//i.test(ua))         return 'firefox';
+  // Safari check: has "Safari/" but NOT "Chrome/" or "Chromium/" or "HeadlessChrome/"
+  if (/\bSafari\//i.test(ua) && !/Chrome|Chromium|HeadlessChrome/i.test(ua)) return 'safari';
+  if (/(?:\b|Headless)Chrom(?:e|ium)\//i.test(ua))  return 'chrome';
+  return 'other';
+}
+
+/**
+ * Extract major browser version from a User-Agent string.
+ * @param {string} ua
+ * @returns {number|null}
+ */
+function extractMajorVersion(ua) {
+  // Try common version patterns in order of specificity
+  let m = ua.match(/\bEdg(?:e|A)?\/(\d+)/);
+  if (m) return parseInt(m[1], 10);
+  m = ua.match(/\bFirefox\/(\d+)/);
+  if (m) return parseInt(m[1], 10);
+  // Chrome / Chromium / HeadlessChrome
+  m = ua.match(/(?:\b|Headless)Chrom(?:e|ium)\/(\d+)/);
+  if (m) return parseInt(m[1], 10);
+  // Safari: Version/17.x  (not the Safari/605 build number)
+  m = ua.match(/\bVersion\/(\d+)/);
+  if (m) return parseInt(m[1], 10);
+  // Generic: first thing/number pattern
+  m = ua.match(/\/(\d+)/);
+  if (m) return parseInt(m[1], 10);
+  return null;
+}
+
+/**
+ * Bucket a major version number into a range token.
+ * @param {number|null} ver
+ * @returns {string}
+ */
+function bucketVersion(ver) {
+  if (ver == null) return '0-79';
+  if (ver < 80)  return '0-79';
+  if (ver < 100) return '80-99';
+  if (ver < 120) return '100-119';
+  if (ver < 140) return '120-139';
+  return '140+';
+}
+
+// ── §6.3.1  extractUAFeatures ──────────────────────────────────────────────
+/**
+ * Parse a User-Agent string into an SF-Dictionary of derived features.
+ *
+ * @param {string|null|undefined} userAgent  Raw User-Agent string
+ * @returns {string|null}  SF-Dictionary string or null if absent/empty
+ */
+export function extractUAFeatures(userAgent) {
+  if (!userAgent) return null;
+  const ua = userAgent.trim();
+  if (ua === '') return null;
+
+  const device   = detectDevice(ua);
+  const platform = detectPlatform(ua);
+  const family   = detectFamily(ua);
+  const ver      = bucketVersion(extractMajorVersion(ua));
+
+  const parts = [`dpf=${device}/${platform}/${family}`, `ver=${ver}`];
+
+  if (/^Mozilla\//i.test(ua)) parts.push('browser');
+
+  if (HEADLESS_MARKERS.some(re => re.test(ua))) parts.push('headless');
+  if (AUTOMATION_MARKERS.some(re => re.test(ua))) parts.push('automation');
+
+  parts.push(`entropy=${computeUAEntropy(ua)}`);
+
+  return parts.join(', ');
+}
+
+// ── §6.3.2  computeUAHMAC ─────────────────────────────────────────────────
+/**
+ * Compute HMAC-SHA256 of the raw User-Agent, returned as an RFC 8941
+ * Byte Sequence string (:base64:).
+ *
+ * Uses crypto.subtle — compatible with Cloudflare Workers and modern Node.
+ *
+ * @param {string} userAgent  Raw User-Agent string
+ * @param {string} hmacKey    HMAC secret key (plain text)
+ * @returns {Promise<string|null>}  RFC 8941 Byte Sequence or null if inputs missing
+ */
+export async function computeUAHMAC(userAgent, hmacKey) {
+  if (!userAgent || !hmacKey) return null;
+
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw', enc.encode(hmacKey),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false, ['sign']
+  );
+  const sig = await crypto.subtle.sign('HMAC', key, enc.encode(userAgent));
+  const b64 = btoa(String.fromCharCode(...new Uint8Array(sig)));
+  return `:${b64}:`;
+}
+
+// ── §6.4  computeConfidenceToken ───────────────────────────────────────────
+/**
+ * Compute the confidence token.
+ * ct = SHA-256(userAgent + acceptLanguage + secChUA)[0:8] hex
+ *
+ * Matches the logic in cloud-api computeConfidenceFingerprint().
+ *
+ * @param {string|null|undefined} userAgent       Raw User-Agent
+ * @param {string|null|undefined} acceptLanguage  Raw Accept-Language
+ * @param {string|null|undefined} secChUA         Raw Sec-CH-UA
+ * @returns {Promise<string>}  8-char hex token, never null
+ */
+export async function computeConfidenceToken(userAgent, acceptLanguage, secChUA) {
+  const ua   = userAgent || '';
+  const lang = acceptLanguage || '';
+  const ch   = secChUA || '';
+
+  const msgBuffer  = new TextEncoder().encode(ua + lang + ch);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
+  const hashArray  = Array.from(new Uint8Array(hashBuffer));
+  const hex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+  return hex.slice(0, 8);
+}