@oxyhq/core 10.1.5 → 10.2.0

package/dist/esm/server/rateLimit.js

@@ -1,3 +1,5 @@
+import { createHmac } from 'node:crypto';
+import { isIPv4, isIPv6 } from 'node:net';
 import rateLimit from 'express-rate-limit';
 /**
  * Built-in exemptions. A media app's cover-art/avatar fan-out and HLS
@@ -15,9 +17,98 @@ function isBuiltInExempt(req) {
         path === '/health' ||
         path.endsWith('/health'));
 }
-/** IPv6-safe IP key generator (replaces colons to avoid Redis namespace issues). */
-function ipKeyGenerator(ip) {
-    return ip.replace(/:/g, '_');
+/**
+ * Anonymous rate-limit keys must be PRIVACY-PRESERVING: the raw client IP must
+ * never reach a store at rest (in-memory or Redis). We therefore HMAC-hash the
+ * IP into a short, transient-only bucket key. Two IPv6-specific concerns shape
+ * the pre-hash normalization:
+ *
+ *  - IPv6 hosts are typically handed an entire /64 (often a /56), so a single
+ *    host can rotate through an enormous address space and evade a per-address
+ *    limit. We bucket IPv6 to its /56 prefix BEFORE hashing.
+ *  - express-rate-limit only exposes an `ipKeyGenerator` /56 helper from v8
+ *    onwards; `@oxyhq/core` pins v7 (peer `^7.0.0`), so the masking is
+ *    implemented here rather than pulling a major-version bump of a
+ *    security-critical dependency (and its rate-limit-redis compatibility) into
+ *    an unrelated privacy change. This mirrors `packages/api/src/utils/ipKey.ts`.
+ */
+const IPV6_SUBNET_BITS = 56;
+/** Expand an IPv6 literal (handling `::` and embedded IPv4) to 8 numeric hextets, or null if unparseable. */
+function ipv6Hextets(ip) {
+    let addr = ip;
+    const zone = addr.indexOf('%');
+    if (zone !== -1) {
+        addr = addr.slice(0, zone);
+    }
+    // Embedded IPv4 tail (e.g. `::ffff:203.0.113.7`) → fold the dotted quad into two hextets.
+    const lastColon = addr.lastIndexOf(':');
+    if (lastColon !== -1 && addr.slice(lastColon + 1).includes('.')) {
+        const v4 = addr.slice(lastColon + 1);
+        if (!isIPv4(v4)) {
+            return null;
+        }
+        const octets = v4.split('.').map((part) => Number.parseInt(part, 10));
+        const high = ((octets[0] << 8) | octets[1]).toString(16);
+        const low = ((octets[2] << 8) | octets[3]).toString(16);
+        addr = `${addr.slice(0, lastColon + 1)}${high}:${low}`;
+    }
+    const halves = addr.split('::');
+    if (halves.length > 2) {
+        return null;
+    }
+    const head = halves[0] ? halves[0].split(':') : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    let groups;
+    if (halves.length === 1) {
+        groups = head;
+    }
+    else {
+        const missing = 8 - (head.length + tail.length);
+        if (missing < 0) {
+            return null;
+        }
+        groups = [...head, ...new Array(missing).fill('0'), ...tail];
+    }
+    if (groups.length !== 8) {
+        return null;
+    }
+    const hextets = groups.map((group) => Number.parseInt(group || '0', 16));
+    if (hextets.some((value) => Number.isNaN(value) || value < 0 || value > 0xffff)) {
+        return null;
+    }
+    return hextets;
+}
+/** Mask an IPv6 address to its /{bits} prefix, returned as a canonical hex string. */
+function maskIPv6(ip, bits) {
+    const hextets = ipv6Hextets(ip);
+    if (!hextets) {
+        return ip;
+    }
+    const masked = hextets.map((hextet, index) => {
+        const groupStart = index * 16;
+        if (groupStart >= bits) {
+            return 0;
+        }
+        const keepBits = Math.min(16, bits - groupStart);
+        const mask = keepBits >= 16 ? 0xffff : (0xffff << (16 - keepBits)) & 0xffff;
+        return hextet & mask;
+    });
+    return `${masked.map((hextet) => hextet.toString(16)).join(':')}/${bits}`;
+}
+/**
+ * Hash a client IP into a privacy-preserving bucket key. IPv6 is bucketed to its
+ * /56 prefix first (so a single v6 host can't rotate through its allocation to
+ * mint fresh keys), then HMAC'd with the server-side salt. The salt is resolved
+ * at CALL time (`IP_HASH_SALT`, else `DEVICE_ID_SALT`, else empty) — an empty
+ * salt still hashes, which beats storing a raw IP; backends SHOULD set one of
+ * those envs. The `rl|` namespace ensures a rate-limit key can never collide
+ * with, or be correlated against, a deviceId derivation that reuses the same
+ * salt. The result is a short hex digest with no colons, so it is Redis-safe.
+ */
+function hashAnonymousIp(ip) {
+    const normalized = isIPv6(ip) && !ip.startsWith('::ffff:') ? maskIPv6(ip, IPV6_SUBNET_BITS) : ip;
+    const salt = process.env.IP_HASH_SALT || process.env.DEVICE_ID_SALT || '';
+    return createHmac('sha256', salt).update(`rl|${normalized}`).digest('hex').slice(0, 24);
 }
 /**
  * Resolve the trusted authenticated rate-limit key.
@@ -43,14 +134,17 @@ function resolveTrustedAuthenticatedKey(req) {
     }
     return null;
 }
-/** Resolve the rate-limit key: per trusted authenticated identity, else per (IPv6-safe) IP. */
+/** Resolve the rate-limit key: per trusted authenticated identity, else per hashed (IPv6-bucketed) IP. */
 function resolveKey(req) {
     const authenticatedKey = resolveTrustedAuthenticatedKey(req);
     if (authenticatedKey) {
         return authenticatedKey;
     }
-    const ip = req.ip || req.socket.remoteAddress || 'unknown';
-    return ipKeyGenerator(ip);
+    const ip = req.ip || req.socket.remoteAddress;
+    if (!ip) {
+        return 'unknown';
+    }
+    return hashAnonymousIp(ip);
 }
 /**
  * Build the composed Oxy rate-limit middleware. See module docs for rationale.