@oxyhq/core 10.1.5 → 10.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "10.1.5",
+  "version": "10.2.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/server/__tests__/rateLimit.test.ts

@@ -26,6 +26,8 @@ interface RateLimitTestRequest extends Request {
   observedKey?: string;
 }
 
+const HEX24 = /^[0-9a-f]{24}$/;
+
 function makeOxy(authHandler: RequestHandler): OxyServices {
   return {
     auth: jest.fn(() => authHandler),
@@ -33,17 +35,37 @@ function makeOxy(authHandler: RequestHandler): OxyServices {
 }
 
 function makeRequest(overrides: Partial<RateLimitTestRequest> = {}): RateLimitTestRequest {
+  const ip = overrides.ip ?? '203.0.113.9';
   return {
     method: 'GET',
     path: '/api/test',
-    ip: '203.0.113.9',
-    socket: { remoteAddress: '203.0.113.9' },
+    ip,
+    socket: { remoteAddress: ip },
     ...overrides,
   } as RateLimitTestRequest;
 }
 
+/** Run the anonymous limiter for a bare IP and return the store key it produced. */
+function keyForIp(ip: string): string {
+  const oxy = makeOxy((_req: Request, _res: Response, next: NextFunction) => next());
+  const req = makeRequest({ ip });
+  createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+  if (typeof req.observedKey !== 'string') {
+    throw new Error('key generator did not run');
+  }
+  return req.observedKey;
+}
+
 describe('@oxyhq/core/server rate limiter', () => {
+  const originalEnv = {
+    IP_HASH_SALT: process.env.IP_HASH_SALT,
+    DEVICE_ID_SALT: process.env.DEVICE_ID_SALT,
+  };
+
   beforeEach(() => {
+    // Isolate salt resolution from any ambient env so key assertions are deterministic.
+    delete process.env.IP_HASH_SALT;
+    delete process.env.DEVICE_ID_SALT;
     rateLimitMock.mockImplementation((options: CapturedRateLimitOptions) => {
       return (req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
         req.observedMax = options.max(req);
@@ -55,6 +77,10 @@ describe('@oxyhq/core/server rate limiter', () => {
 
   afterEach(() => {
     jest.clearAllMocks();
+    if (originalEnv.IP_HASH_SALT === undefined) delete process.env.IP_HASH_SALT;
+    else process.env.IP_HASH_SALT = originalEnv.IP_HASH_SALT;
+    if (originalEnv.DEVICE_ID_SALT === undefined) delete process.env.DEVICE_ID_SALT;
+    else process.env.DEVICE_ID_SALT = originalEnv.DEVICE_ID_SALT;
   });
 
   it('does not trust locally decoded non-session JWT identities for quota or bucket keys', () => {
@@ -73,7 +99,9 @@ describe('@oxyhq/core/server rate limiter', () => {
     );
 
     expect(req.observedMax).toBe(600);
-    expect(req.observedKey).toBe('203.0.113.9');
+    // Anonymous callers are bucketed by a hashed key, NEVER the raw IP.
+    expect(req.observedKey).toMatch(HEX24);
+    expect(req.observedKey).not.toContain('203.0.113.9');
     expect(next).toHaveBeenCalledTimes(1);
   });
 
@@ -93,6 +121,7 @@ describe('@oxyhq/core/server rate limiter', () => {
     );
 
     expect(req.observedMax).toBe(5000);
+    // Authenticated identities are keyed by the user id verbatim — NOT hashed.
     expect(req.observedKey).toBe('user:validated-user');
   });
 
@@ -110,7 +139,72 @@ describe('@oxyhq/core/server rate limiter', () => {
     );
 
     expect(req.observedMax).toBe(600);
-    expect(req.observedKey).toBe('203.0.113.9');
+    expect(req.observedKey).toMatch(HEX24);
+    expect(req.observedKey).not.toContain('203.0.113.9');
     expect(next).toHaveBeenCalledTimes(1);
   });
+
+  describe('anonymous key hashing', () => {
+    it('produces a deterministic 24-hex key that never contains the raw IP', () => {
+      const first = keyForIp('203.0.113.9');
+      const second = keyForIp('203.0.113.9');
+
+      expect(first).toMatch(HEX24);
+      expect(first).toBe(second);
+      expect(first).not.toContain('203.0.113.9');
+    });
+
+    it('produces different keys for different IPv4 addresses', () => {
+      expect(keyForIp('203.0.113.9')).not.toBe(keyForIp('198.51.100.7'));
+    });
+
+    it('buckets IPv6 addresses in the same /56 to the same key', () => {
+      // 2001:db8:abcd:ee11 and 2001:db8:abcd:eeff share the /56 prefix (top byte of
+      // the 4th hextet is 0xee for both); the differing bits are host bits.
+      const a = keyForIp('2001:db8:abcd:ee11::1');
+      const b = keyForIp('2001:db8:abcd:eeff::9999');
+
+      expect(a).toMatch(HEX24);
+      expect(a).toBe(b);
+    });
+
+    it('produces different keys for IPv6 addresses in different /56 prefixes', () => {
+      const sameFiftySix = keyForIp('2001:db8:abcd:ee11::1');
+      const otherFiftySix = keyForIp('2001:db8:abcd:ff11::1');
+
+      expect(sameFiftySix).not.toBe(otherFiftySix);
+    });
+
+    it('salts the hash with IP_HASH_SALT so keys are not portable across salts', () => {
+      const unsalted = keyForIp('203.0.113.9');
+
+      process.env.IP_HASH_SALT = 'salt-a';
+      const saltedA = keyForIp('203.0.113.9');
+
+      process.env.IP_HASH_SALT = 'salt-b';
+      const saltedB = keyForIp('203.0.113.9');
+
+      expect(saltedA).toMatch(HEX24);
+      expect(saltedA).not.toBe(unsalted);
+      expect(saltedB).not.toBe(saltedA);
+    });
+
+    it('prefers IP_HASH_SALT over DEVICE_ID_SALT', () => {
+      process.env.DEVICE_ID_SALT = 'device-salt';
+      const deviceOnly = keyForIp('203.0.113.9');
+
+      process.env.IP_HASH_SALT = 'ip-salt';
+      const ipPreferred = keyForIp('203.0.113.9');
+
+      expect(ipPreferred).not.toBe(deviceOnly);
+    });
+
+    it('falls back to the literal "unknown" key when no IP is resolvable', () => {
+      const oxy = makeOxy((_req: Request, _res: Response, next: NextFunction) => next());
+      const req = makeRequest({ ip: undefined, socket: {} as Request['socket'] });
+      createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+
+      expect(req.observedKey).toBe('unknown');
+    });
+  });
 });

package/src/server/rateLimit.ts

@@ -1,3 +1,5 @@
+import { createHmac } from 'node:crypto';
+import { isIPv4, isIPv6 } from 'node:net';
 import type { Request, RequestHandler } from 'express';
 import rateLimit, { type Store } from 'express-rate-limit';
 import type { OxyServices } from '../OxyServices';
@@ -99,9 +101,103 @@ function isBuiltInExempt(req: Request): boolean {
   );
 }
 
-/** IPv6-safe IP key generator (replaces colons to avoid Redis namespace issues). */
-function ipKeyGenerator(ip: string): string {
-  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: string): number[] | null {
+  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: string[];
+  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: string, bits: number): string {
+  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: string): string {
+  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);
 }
 
 /**
@@ -132,14 +228,17 @@ function resolveTrustedAuthenticatedKey(req: OxyAuthedRequest): string | null {
   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: OxyAuthedRequest): string {
   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);
 }
 
 /**