@pocketping/sdk-node 1.0.0 → 1.1.0

package/README.md

@@ -69,7 +69,78 @@ const pp = new PocketPing({
   // Protocol version settings
   protocolVersion: '1.0',
   minSupportedVersion: '0.1',
+
+  // IP filtering (see IP Filtering section below)
+  ipFilter: {
+    enabled: true,
+    mode: 'blocklist',
+    blocklist: ['203.0.113.0/24'],
+  },
+});
+```
+
+## IP Filtering
+
+Block or allow specific IP addresses or CIDR ranges:
+
+```typescript
+const pp = new PocketPing({
+  ipFilter: {
+    enabled: true,
+    mode: 'blocklist',  // 'allowlist' | 'blocklist' | 'both'
+    blocklist: [
+      '203.0.113.0/24',   // CIDR range
+      '198.51.100.50',    // Single IP
+    ],
+    allowlist: [
+      '10.0.0.0/8',       // Internal network
+    ],
+    logBlocked: true,     // Log blocked requests (default: true)
+    blockedStatusCode: 403,
+    blockedMessage: 'Forbidden',
+  },
 });
+
+// Or with a custom filter function
+const pp = new PocketPing({
+  ipFilter: {
+    enabled: true,
+    mode: 'blocklist',
+    customFilter: (ip, request) => {
+      // Return true to allow, false to block, null to defer to list-based filtering
+      if (ip.startsWith('192.168.')) return true;  // Always allow local
+      return null;  // Use blocklist/allowlist
+    },
+  },
+});
+```
+
+### Modes
+
+| Mode | Behavior |
+|------|----------|
+| `blocklist` | Block IPs in blocklist, allow all others (default) |
+| `allowlist` | Only allow IPs in allowlist, block all others |
+| `both` | Allowlist takes precedence, then blocklist is applied |
+
+### CIDR Support
+
+The SDK supports CIDR notation for IP ranges:
+- Single IP: `192.168.1.1` (treated as `/32`)
+- Class C: `192.168.1.0/24` (256 addresses)
+- Class B: `172.16.0.0/16` (65,536 addresses)
+- Class A: `10.0.0.0/8` (16M addresses)
+
+### Manual IP Check
+
+```typescript
+// Check IP manually
+const result = pp.checkIpFilter('192.168.1.50');
+// result: { allowed: boolean, reason: string, matchedRule?: string }
+
+// Get client IP from request headers
+const clientIp = pp.getClientIp(request.headers);
+// Checks: CF-Connecting-IP, X-Real-IP, X-Forwarded-For
 ```
 
 ## Architecture Options

package/dist/index.cjs

@@ -92,6 +92,71 @@ var MemoryStorage = class {
   }
 };
 
+// src/utils/ip-filter.ts
+function ipToNumber(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let num = 0;
+  for (const part of parts) {
+    const n = parseInt(part, 10);
+    if (isNaN(n) || n < 0 || n > 255) return null;
+    num = num << 8 | n;
+  }
+  return num >>> 0;
+}
+function parseCidr(cidr) {
+  const [ip, bits] = cidr.split("/");
+  const base = ipToNumber(ip);
+  if (base === null) return null;
+  const prefix = bits ? parseInt(bits, 10) : 32;
+  if (isNaN(prefix) || prefix < 0 || prefix > 32) return null;
+  const mask = prefix === 0 ? 0 : ~0 << 32 - prefix >>> 0;
+  return { base: (base & mask) >>> 0, mask };
+}
+function ipMatchesCidr(ip, cidr) {
+  const ipNum = ipToNumber(ip);
+  if (ipNum === null) return false;
+  const parsed = parseCidr(cidr);
+  if (!parsed) return false;
+  return (ipNum & parsed.mask) >>> 0 === parsed.base;
+}
+function ipMatchesAny(ip, list) {
+  return list.some((entry) => ipMatchesCidr(ip, entry));
+}
+function shouldAllowIp(ip, config) {
+  const { mode = "blocklist", allowlist = [], blocklist = [] } = config;
+  switch (mode) {
+    case "allowlist":
+      if (ipMatchesAny(ip, allowlist)) {
+        return { allowed: true, reason: "allowlist" };
+      }
+      return { allowed: false, reason: "not_in_allowlist" };
+    case "blocklist":
+      if (ipMatchesAny(ip, blocklist)) {
+        return { allowed: false, reason: "blocklist" };
+      }
+      return { allowed: true, reason: "default" };
+    case "both":
+      if (ipMatchesAny(ip, allowlist)) {
+        return { allowed: true, reason: "allowlist" };
+      }
+      if (ipMatchesAny(ip, blocklist)) {
+        return { allowed: false, reason: "blocklist" };
+      }
+      return { allowed: true, reason: "default" };
+    default:
+      return { allowed: true, reason: "default" };
+  }
+}
+async function checkIpFilter(ip, config, requestInfo) {
+  if (config.customFilter) {
+    const customResult = await config.customFilter(ip, requestInfo);
+    if (customResult === true) return { allowed: true, reason: "custom" };
+    if (customResult === false) return { allowed: false, reason: "custom" };
+  }
+  return shouldAllowIp(ip, config);
+}
+
 // src/pocketping.ts
 function getClientIp(req) {
   const forwarded = req.headers["x-forwarded-for"];
@@ -179,6 +244,34 @@ var PocketPing = class {
         res.end();
         return;
       }
+      if (this.config.ipFilter?.enabled) {
+        const clientIp = getClientIp(req);
+        const filterResult = await checkIpFilter(clientIp, this.config.ipFilter, {
+          path
+        });
+        if (!filterResult.allowed) {
+          if (this.config.ipFilter.logBlocked !== false) {
+            const logEvent = {
+              type: "blocked",
+              ip: clientIp,
+              reason: filterResult.reason,
+              path,
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            if (this.config.ipFilter.logger) {
+              this.config.ipFilter.logger(logEvent);
+            } else {
+              console.log(`[PocketPing] IP blocked: ${clientIp} - reason: ${filterResult.reason}`);
+            }
+          }
+          res.statusCode = this.config.ipFilter.blockedStatusCode ?? 403;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({
+            error: this.config.ipFilter.blockedMessage ?? "Forbidden"
+          }));
+          return;
+        }
+      }
       const widgetVersion = req.headers["x-pocketping-version"];
       const versionCheck = this.checkWidgetVersion(widgetVersion);
       this.setVersionHeaders(res, versionCheck);
@@ -287,7 +380,31 @@ var PocketPing = class {
       server,
       path: "/pocketping/stream"
     });
-    this.wss.on("connection", (ws, req) => {
+    this.wss.on("connection", async (ws, req) => {
+      if (this.config.ipFilter?.enabled) {
+        const clientIp = getClientIp(req);
+        const filterResult = await checkIpFilter(clientIp, this.config.ipFilter, {
+          path: "/pocketping/stream"
+        });
+        if (!filterResult.allowed) {
+          if (this.config.ipFilter.logBlocked !== false) {
+            const logEvent = {
+              type: "blocked",
+              ip: clientIp,
+              reason: filterResult.reason,
+              path: "/pocketping/stream",
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            if (this.config.ipFilter.logger) {
+              this.config.ipFilter.logger(logEvent);
+            } else {
+              console.log(`[PocketPing] WS IP blocked: ${clientIp} - reason: ${filterResult.reason}`);
+            }
+          }
+          ws.close(4003, this.config.ipFilter.blockedMessage ?? "Forbidden");
+          return;
+        }
+      }
       const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
       const sessionId = url.searchParams.get("sessionId");
       if (!sessionId) {

package/dist/index.d.cts

@@ -56,6 +56,52 @@ interface AIProvider {
     isAvailable(): Promise<boolean>;
 }
 
+/**
+ * IP Filtering utilities for PocketPing SDK
+ * Supports CIDR notation and individual IP addresses
+ */
+type IpFilterMode = 'allowlist' | 'blocklist' | 'both';
+interface IpFilterConfig {
+    /** Enable/disable IP filtering (default: false) */
+    enabled?: boolean;
+    /** Filter mode (default: 'blocklist') */
+    mode?: IpFilterMode;
+    /** IPs/CIDRs to allow (e.g., ['192.168.1.0/24', '10.0.0.1']) */
+    allowlist?: string[];
+    /** IPs/CIDRs to block (e.g., ['203.0.113.0/24', '198.51.100.50']) */
+    blocklist?: string[];
+    /** Custom filter callback for advanced logic */
+    customFilter?: IpFilterCallback;
+    /** Log blocked requests for security auditing (default: true) */
+    logBlocked?: boolean;
+    /** Custom logger function */
+    logger?: (event: IpFilterLogEvent) => void;
+    /** HTTP status code for blocked requests (default: 403) */
+    blockedStatusCode?: number;
+    /** Response message for blocked requests (default: 'Forbidden') */
+    blockedMessage?: string;
+    /** Trust proxy headers (X-Forwarded-For, etc.) (default: true) */
+    trustProxy?: boolean;
+    /** Ordered list of headers to check for client IP */
+    proxyHeaders?: string[];
+}
+interface IpFilterLogEvent {
+    type: 'blocked' | 'allowed';
+    ip: string;
+    reason: 'allowlist' | 'blocklist' | 'custom' | 'not_in_allowlist' | 'default';
+    path: string;
+    timestamp: Date;
+    sessionId?: string;
+}
+/**
+ * Custom IP filter callback
+ * Return true to allow, false to block, undefined to defer to list-based filtering
+ */
+type IpFilterCallback = (ip: string, request: {
+    path: string;
+    sessionId?: string;
+}) => boolean | undefined | Promise<boolean | undefined>;
+
 interface PocketPingConfig {
     /** Storage adapter for sessions and messages */
     storage?: Storage | 'memory';
@@ -89,6 +135,8 @@ interface PocketPingConfig {
     versionWarningMessage?: string;
     /** URL to upgrade instructions */
     versionUpgradeUrl?: string;
+    /** IP filtering configuration (allowlist/blocklist) */
+    ipFilter?: IpFilterConfig;
 }
 interface AIConfig {
     provider: AIProvider | 'openai' | 'gemini' | 'anthropic';

package/dist/index.d.ts

@@ -56,6 +56,52 @@ interface AIProvider {
     isAvailable(): Promise<boolean>;
 }
 
+/**
+ * IP Filtering utilities for PocketPing SDK
+ * Supports CIDR notation and individual IP addresses
+ */
+type IpFilterMode = 'allowlist' | 'blocklist' | 'both';
+interface IpFilterConfig {
+    /** Enable/disable IP filtering (default: false) */
+    enabled?: boolean;
+    /** Filter mode (default: 'blocklist') */
+    mode?: IpFilterMode;
+    /** IPs/CIDRs to allow (e.g., ['192.168.1.0/24', '10.0.0.1']) */
+    allowlist?: string[];
+    /** IPs/CIDRs to block (e.g., ['203.0.113.0/24', '198.51.100.50']) */
+    blocklist?: string[];
+    /** Custom filter callback for advanced logic */
+    customFilter?: IpFilterCallback;
+    /** Log blocked requests for security auditing (default: true) */
+    logBlocked?: boolean;
+    /** Custom logger function */
+    logger?: (event: IpFilterLogEvent) => void;
+    /** HTTP status code for blocked requests (default: 403) */
+    blockedStatusCode?: number;
+    /** Response message for blocked requests (default: 'Forbidden') */
+    blockedMessage?: string;
+    /** Trust proxy headers (X-Forwarded-For, etc.) (default: true) */
+    trustProxy?: boolean;
+    /** Ordered list of headers to check for client IP */
+    proxyHeaders?: string[];
+}
+interface IpFilterLogEvent {
+    type: 'blocked' | 'allowed';
+    ip: string;
+    reason: 'allowlist' | 'blocklist' | 'custom' | 'not_in_allowlist' | 'default';
+    path: string;
+    timestamp: Date;
+    sessionId?: string;
+}
+/**
+ * Custom IP filter callback
+ * Return true to allow, false to block, undefined to defer to list-based filtering
+ */
+type IpFilterCallback = (ip: string, request: {
+    path: string;
+    sessionId?: string;
+}) => boolean | undefined | Promise<boolean | undefined>;
+
 interface PocketPingConfig {
     /** Storage adapter for sessions and messages */
     storage?: Storage | 'memory';
@@ -89,6 +135,8 @@ interface PocketPingConfig {
     versionWarningMessage?: string;
     /** URL to upgrade instructions */
     versionUpgradeUrl?: string;
+    /** IP filtering configuration (allowlist/blocklist) */
+    ipFilter?: IpFilterConfig;
 }
 interface AIConfig {
     provider: AIProvider | 'openai' | 'gemini' | 'anthropic';

package/dist/index.js

@@ -65,6 +65,71 @@ var MemoryStorage = class {
   }
 };
 
+// src/utils/ip-filter.ts
+function ipToNumber(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let num = 0;
+  for (const part of parts) {
+    const n = parseInt(part, 10);
+    if (isNaN(n) || n < 0 || n > 255) return null;
+    num = num << 8 | n;
+  }
+  return num >>> 0;
+}
+function parseCidr(cidr) {
+  const [ip, bits] = cidr.split("/");
+  const base = ipToNumber(ip);
+  if (base === null) return null;
+  const prefix = bits ? parseInt(bits, 10) : 32;
+  if (isNaN(prefix) || prefix < 0 || prefix > 32) return null;
+  const mask = prefix === 0 ? 0 : ~0 << 32 - prefix >>> 0;
+  return { base: (base & mask) >>> 0, mask };
+}
+function ipMatchesCidr(ip, cidr) {
+  const ipNum = ipToNumber(ip);
+  if (ipNum === null) return false;
+  const parsed = parseCidr(cidr);
+  if (!parsed) return false;
+  return (ipNum & parsed.mask) >>> 0 === parsed.base;
+}
+function ipMatchesAny(ip, list) {
+  return list.some((entry) => ipMatchesCidr(ip, entry));
+}
+function shouldAllowIp(ip, config) {
+  const { mode = "blocklist", allowlist = [], blocklist = [] } = config;
+  switch (mode) {
+    case "allowlist":
+      if (ipMatchesAny(ip, allowlist)) {
+        return { allowed: true, reason: "allowlist" };
+      }
+      return { allowed: false, reason: "not_in_allowlist" };
+    case "blocklist":
+      if (ipMatchesAny(ip, blocklist)) {
+        return { allowed: false, reason: "blocklist" };
+      }
+      return { allowed: true, reason: "default" };
+    case "both":
+      if (ipMatchesAny(ip, allowlist)) {
+        return { allowed: true, reason: "allowlist" };
+      }
+      if (ipMatchesAny(ip, blocklist)) {
+        return { allowed: false, reason: "blocklist" };
+      }
+      return { allowed: true, reason: "default" };
+    default:
+      return { allowed: true, reason: "default" };
+  }
+}
+async function checkIpFilter(ip, config, requestInfo) {
+  if (config.customFilter) {
+    const customResult = await config.customFilter(ip, requestInfo);
+    if (customResult === true) return { allowed: true, reason: "custom" };
+    if (customResult === false) return { allowed: false, reason: "custom" };
+  }
+  return shouldAllowIp(ip, config);
+}
+
 // src/pocketping.ts
 function getClientIp(req) {
   const forwarded = req.headers["x-forwarded-for"];
@@ -152,6 +217,34 @@ var PocketPing = class {
         res.end();
         return;
       }
+      if (this.config.ipFilter?.enabled) {
+        const clientIp = getClientIp(req);
+        const filterResult = await checkIpFilter(clientIp, this.config.ipFilter, {
+          path
+        });
+        if (!filterResult.allowed) {
+          if (this.config.ipFilter.logBlocked !== false) {
+            const logEvent = {
+              type: "blocked",
+              ip: clientIp,
+              reason: filterResult.reason,
+              path,
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            if (this.config.ipFilter.logger) {
+              this.config.ipFilter.logger(logEvent);
+            } else {
+              console.log(`[PocketPing] IP blocked: ${clientIp} - reason: ${filterResult.reason}`);
+            }
+          }
+          res.statusCode = this.config.ipFilter.blockedStatusCode ?? 403;
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({
+            error: this.config.ipFilter.blockedMessage ?? "Forbidden"
+          }));
+          return;
+        }
+      }
       const widgetVersion = req.headers["x-pocketping-version"];
       const versionCheck = this.checkWidgetVersion(widgetVersion);
       this.setVersionHeaders(res, versionCheck);
@@ -260,7 +353,31 @@ var PocketPing = class {
       server,
       path: "/pocketping/stream"
     });
-    this.wss.on("connection", (ws, req) => {
+    this.wss.on("connection", async (ws, req) => {
+      if (this.config.ipFilter?.enabled) {
+        const clientIp = getClientIp(req);
+        const filterResult = await checkIpFilter(clientIp, this.config.ipFilter, {
+          path: "/pocketping/stream"
+        });
+        if (!filterResult.allowed) {
+          if (this.config.ipFilter.logBlocked !== false) {
+            const logEvent = {
+              type: "blocked",
+              ip: clientIp,
+              reason: filterResult.reason,
+              path: "/pocketping/stream",
+              timestamp: /* @__PURE__ */ new Date()
+            };
+            if (this.config.ipFilter.logger) {
+              this.config.ipFilter.logger(logEvent);
+            } else {
+              console.log(`[PocketPing] WS IP blocked: ${clientIp} - reason: ${filterResult.reason}`);
+            }
+          }
+          ws.close(4003, this.config.ipFilter.blockedMessage ?? "Forbidden");
+          return;
+        }
+      }
       const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
       const sessionId = url.searchParams.get("sessionId");
       if (!sessionId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pocketping/sdk-node",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Node.js SDK for implementing PocketPing protocol",
   "main": "dist/index.cjs",
@@ -22,12 +22,16 @@
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "lint": "biome check src tests",
+    "lint:fix": "biome check --write src tests",
+    "format": "biome format --write src tests"
   },
   "dependencies": {
     "ws": "^8.16.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
     "@types/ws": "^8.5.10",
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",