@paywalls-net/filter 1.3.1 → 1.3.3

package/README.md

@@ -12,6 +12,24 @@ npm install @paywalls-net/filter
 - `PAYWALLS_PUBLISHER_ID`: The unique identifier for the publisher using paywalls.net services.
 - `PAYWALLS_CLOUD_API_KEY`: The API key for accessing paywalls.net services. NOTE: This key should be treated like a password and kept secret and stored in a secure secrets vault or environment variable.
 
+## Architecture: Path Prefix Ownership
+
+The SDK uses a **path prefix ownership strategy** for VAI (Validated Actor Inventory) endpoints. All requests to `/pw/*` are automatically proxied to the paywalls.net cloud-api service with API key authentication.
+
+### Benefits
+- **Version Independent**: New VAI endpoints work automatically without SDK updates
+- **Reduced Publisher Friction**: Publishers don't need to update client code when new features are added
+- **Future Proof**: Supports nested paths like `/pw/v2/*` or `/pw/analytics/*`
+
+### Proxied Endpoints
+Any request matching `/pw/*` is proxied with authentication:
+- `/pw/vai.json` - VAI classification (JSON)
+- `/pw/vai.js` - VAI classification (JavaScript)
+- `/pw/jwks.json` - JSON Web Key Set for signature verification
+- Future endpoints automatically supported
+
+This strategy minimizes version coupling between the client SDK and the paywalls.net platform.
+
 ## Usage
 The following is an example of using the SDK with Cloudflare Workers:
 

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.1",
+  "version": "1.3.3",
   "publishConfig": {
     "access": "public"
   },

package/src/index.js

@@ -52,23 +52,36 @@ function getAllHeaders(request) {
 }
 
 /**
- * Check if the request is for a VAI endpoint (vai.json or vai.js)
+ * Check if the request is for a VAI endpoint (vai.json, vai.js, or jwks.json)
  * @param {Request} request - The incoming request
  * @param {string} vaiPath - The path prefix for VAI endpoints (default: '/pw')
  * @returns {boolean} - True if this is a VAI endpoint request
  */
+/**
+ * Check if request is for a VAI endpoint.
+ * Uses path prefix matching to proxy all /pw/* requests without hardcoding specific endpoints.
+ * This makes the SDK future-proof - new VAI endpoints work automatically without SDK updates.
+ * 
+ * @param {Request} request - The incoming request
+ * @param {string} vaiPath - VAI path prefix (default: '/pw')
+ * @returns {boolean} - True if request should be proxied to cloud-api
+ */
 function isVAIRequest(request, vaiPath = '/pw') {
     try {
         const url = new URL(request.url || `http://host${request.uri || ''}`);
         const pathname = url.pathname;
-        return pathname === `${vaiPath}/vai.json` || pathname === `${vaiPath}/vai.js`;
+        // Proxy everything under the VAI path prefix
+        return pathname.startsWith(`${vaiPath}/`);
     } catch (err) {
         return false;
     }
 }
 
 /**
- * Proxy VAI requests to the cloud-api service
+ * Proxy VAI requests to the cloud-api service.
+ * Proxies the entire request path without endpoint-specific logic,
+ * allowing new VAI endpoints to work automatically.
+ * 
  * @param {Object} cfg - Configuration object with paywallsAPIHost and paywallsAPIKey
  * @param {Request} request - The incoming request
  * @returns {Promise<Response>} - The proxied response from cloud-api
@@ -76,8 +89,9 @@ function isVAIRequest(request, vaiPath = '/pw') {
 async function proxyVAIRequest(cfg, request) {
     try {
         const url = new URL(request.url || `http://host${request.uri || ''}`);
-        const isJson = url.pathname.endsWith('/vai.json');
-        const cloudApiPath = isJson ? '/pw/vai.json' : '/pw/vai.js';
+        
+        // Proxy the entire path as-is (path prefix ownership strategy)
+        const cloudApiPath = url.pathname + url.search;
         
         // Get all request headers
         const headers = getAllHeaders(request);

package/src/user-agent-classification.js

@@ -5,6 +5,39 @@ let cachedUserAgentPatterns = null;
 let cacheTimestamp = null;
 const CACHE_DURATION = 60 * 60 * 1000; // 1 hour
 
+// Cache for user agent classifications
+// 
+// CACHE STRATEGY CONSIDERATIONS:
+// 
+// Current approach: Raw user-agent string as cache key
+// - Pro: No parsing overhead before cache lookup
+// - Pro: Exact matches are very fast
+// - Con: User-agents with minor version differences create separate cache entries
+// - Con: Cache could grow large with many unique UAs (especially browser traffic)
+//
+// Alternative approaches to consider:
+// 1. Normalized keys (e.g., browser name + major version + OS)
+//    - Would improve hit rate and reduce memory
+//    - But adds parsing cost before every cache check
+//    - Risk: Might miss pattern-specific matches if patterns are version-sensitive
+//
+// 2. LRU cache with size limit
+//    - Bounds memory usage
+//    - Evicts least-recently-used entries
+//    - Good if traffic patterns are consistent
+//
+// 3. Separate caches for bots vs browsers
+//    - Bot UAs are typically more stable (better cache hit rate)
+//    - Browser UAs change frequently with versions (lower hit rate)
+//    - Could optimize each differently
+//
+// Decision: Start with raw UA keys until we have production metrics showing:
+// - Actual cache size growth
+// - Cache hit rates
+// - Memory pressure
+// Then optimize based on data rather than speculation.
+let classificationCache = new Map();
+
 /**
  * Fetch user agent patterns from the API and cache them.
  * @returns {Promise<Array>} The user agent patterns.
@@ -39,6 +72,10 @@ export async function loadAgentPatterns(cfg) {
         }));
 
         cacheTimestamp = now;
+        
+        // Clear classification cache when patterns are refreshed
+        classificationCache.clear();
+        
         return cachedUserAgentPatterns;
     } catch (error) {
         console.error('Error loading agent patterns:', error);
@@ -53,6 +90,14 @@ export async function loadAgentPatterns(cfg) {
  * @returns {Promise<Object>} An object containing the browser, OS, operator, usage, and user_initiated status.
  */
 export async function classifyUserAgent(cfg, userAgent) {
+    // Check classification cache first (single lookup is more efficient than has + get)
+    const cached = classificationCache.get(userAgent);
+    if (cached !== undefined) {
+        console.log(`User agent classification cache hit for: ${userAgent}`);
+        return cached;
+    }
+    console.log(`User agent classification cache miss for: ${userAgent}`);
+
     const parsedUA = new UAParser(userAgent).getResult();
 
     const browser = parsedUA.browser.name || 'Unknown';
@@ -64,7 +109,7 @@ export async function classifyUserAgent(cfg, userAgent) {
         if (!config.patterns) continue;
         for (const pattern of config.patterns) {
             if (new RegExp(pattern).test(userAgent)) {         
-                return {
+                const result = {
                     operator: config.operator,
                     agent: config.agent || browser,
                     usage: config.usage,
@@ -72,12 +117,18 @@ export async function classifyUserAgent(cfg, userAgent) {
                     browser,
                     os,
                 };
+                // Cache the classification result
+                classificationCache.set(userAgent, result);
+                return result;
             }
         }
     }
 
-    return {
+    const result = {
         browser,
         os
     };
+    // Cache the default classification
+    classificationCache.set(userAgent, result);
+    return result;
 }