@paywalls-net/filter 1.3.2 → 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.2",
+  "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);