@paywalls-net/filter 1.3.2 → 1.3.4

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.2",
+  "version": "1.3.4",
   "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);
@@ -185,6 +199,8 @@ async function checkAgentStatus(cfg, request) {
         account_id: cfg.paywallsPublisherId,
         operator: agentInfo.operator,
         agent: agentInfo.agent,
+        vat: agentInfo.vat,
+        act: agentInfo.act,
         token: token,
         headers: headers
     });
@@ -248,7 +264,8 @@ function isTestBot(request) {
 async function isPaywallsKnownBot(cfg, request) {
     const userAgent = request.headers.get("User-Agent");
     const uaClassification = await classifyUserAgent(cfg, userAgent);
-    return uaClassification.operator && uaClassification.agent;
+    // Classified as non-human by pattern match, or has known operator/agent
+    return (uaClassification.vat && uaClassification.vat !== 'HUMAN') || (uaClassification.operator && uaClassification.agent);
 }
 
 async function isRecognizedBot(cfg, request) {

package/src/user-agent-classification.js

@@ -63,12 +63,23 @@ export async function loadAgentPatterns(cfg) {
             throw new Error(`Failed to fetch agent patterns: ${response.status} ${response.statusText}`);
         }
 
-        const serializedPatterns = await response.json();
+        const data = await response.json();
+
+        // Handle v2 envelope ({ version: 2, patterns: [...] }) or v1 flat array
+        const serializedPatterns = (data && data.version === 2 && Array.isArray(data.patterns))
+            ? data.patterns
+            : Array.isArray(data) ? data : [];
 
         // Deserialize RegExp strings back into RegExp objects
+        // Format: "/pattern/flags" — extract pattern and flags separately
         cachedUserAgentPatterns = serializedPatterns.map((pattern) => ({
             ...pattern,
-            patterns: pattern.patterns.map((regexString) => new RegExp(regexString.slice(1, -1))) // Remove leading and trailing slashes
+            patterns: pattern.patterns.map((regexString) => {
+                const lastSlash = regexString.lastIndexOf('/');
+                const pattern = regexString.slice(1, lastSlash);
+                const flags = regexString.slice(lastSlash + 1);
+                return new RegExp(pattern, flags);
+            })
         }));
 
         cacheTimestamp = now;
@@ -114,6 +125,10 @@ export async function classifyUserAgent(cfg, userAgent) {
                     agent: config.agent || browser,
                     usage: config.usage,
                     user_initiated: config.user_initiated,
+                    purpose: config.purpose,
+                    purpose_mode: config.purpose_mode,
+                    vat: config.vat,
+                    act: config.act,
                     browser,
                     os,
                 };
@@ -126,7 +141,9 @@ export async function classifyUserAgent(cfg, userAgent) {
 
     const result = {
         browser,
-        os
+        os,
+        vat: 'HUMAN',
+        act: 'ACT-3',
     };
     // Cache the default classification
     classificationCache.set(userAgent, result);