@oxy.so/core 1.0.0

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

@@ -0,0 +1,257 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import type { OxyServices } from '../../OxyServices';
+
+const rateLimitMock = jest.fn();
+
+jest.mock('express-rate-limit', () => ({
+  __esModule: true,
+  default: (...args: unknown[]) => rateLimitMock(...args),
+}));
+
+import { createOxyRateLimit } from '../rateLimit';
+
+interface CapturedRateLimitOptions {
+  max: (req: Request) => number;
+  keyGenerator: (req: Request) => string;
+  skip: (req: Request) => boolean;
+}
+
+interface RateLimitTestRequest extends Request {
+  userId?: string | null;
+  user?: { id?: string; _id?: string } | null;
+  sessionId?: string | null;
+  serviceApp?: { appId?: string } | null;
+  serviceActingAs?: { userId?: string } | null;
+  observedMax?: number;
+  observedKey?: string;
+}
+
+const HEX24 = /^[0-9a-f]{24}$/;
+
+function makeOxy(authHandler: RequestHandler): OxyServices {
+  return {
+    auth: jest.fn(() => authHandler),
+  } as unknown as OxyServices;
+}
+
+function makeRequest(overrides: Partial<RateLimitTestRequest> = {}): RateLimitTestRequest {
+  const ip = overrides.ip ?? '203.0.113.9';
+  return {
+    method: 'GET',
+    path: '/api/test',
+    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('@oxy.so/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);
+        req.observedKey = options.keyGenerator(req);
+        next();
+      };
+    });
+  });
+
+  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', () => {
+    const oxy = makeOxy((req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+      req.userId = 'attacker-controlled-user';
+      req.user = { id: 'attacker-controlled-user' };
+      next();
+    });
+    const req = makeRequest();
+    const next = jest.fn();
+
+    createOxyRateLimit(oxy, { authenticatedMax: 5000, anonymousMax: 600 })(
+      req,
+      {} as Response,
+      next,
+    );
+
+    expect(req.observedMax).toBe(600);
+    // 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);
+  });
+
+  it('uses authenticated quota and per-user keys for server-validated sessions', () => {
+    const oxy = makeOxy((req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+      req.userId = 'validated-user';
+      req.user = { id: 'validated-user' };
+      req.sessionId = 'validated-session';
+      next();
+    });
+    const req = makeRequest();
+
+    createOxyRateLimit(oxy, { authenticatedMax: 5000, anonymousMax: 600 })(
+      req,
+      {} as Response,
+      jest.fn(),
+    );
+
+    expect(req.observedMax).toBe(5000);
+    // Authenticated identities are keyed by the user id verbatim — NOT hashed.
+    expect(req.observedKey).toBe('user:validated-user');
+  });
+
+  it('does not clobber an identity a preceding middleware already resolved', () => {
+    // The limiter mutates the SHARED `req`, so the unconditional
+    // `req.userId = null` that `oxy.auth({ optional: true })` writes for every
+    // request it cannot authenticate is not merely a bucketing detail — it
+    // erases the identity for every handler downstream of the limiter too.
+    // The resolver must therefore skip entirely when a user is already present.
+    // This handler stands in for that erasure.
+    const clobberingAuth = jest.fn(
+      (req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+        req.userId = null;
+        req.user = null;
+        req.sessionId = null;
+        next();
+      },
+    );
+    const oxy = makeOxy(clobberingAuth as unknown as RequestHandler);
+    const req = makeRequest({
+      userId: 'resolved-by-the-app',
+      user: { id: 'resolved-by-the-app' },
+      sessionId: 'app-session',
+    });
+
+    createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+
+    expect(req.userId).toBe('resolved-by-the-app');
+    expect(req.user).toEqual({ id: 'resolved-by-the-app' });
+    expect(req.sessionId).toBe('app-session');
+    expect(req.observedKey).toBe('user:resolved-by-the-app');
+    expect(clobberingAuth).not.toHaveBeenCalled();
+  });
+
+  it('still resolves the session when no identity is present yet', () => {
+    const authHandler = jest.fn((req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+      req.userId = 'resolved-by-oxy';
+      req.user = { id: 'resolved-by-oxy' };
+      req.sessionId = 'oxy-session';
+      next();
+    });
+    const oxy = makeOxy(authHandler as unknown as RequestHandler);
+    const req = makeRequest();
+
+    createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+
+    expect(authHandler).toHaveBeenCalledTimes(1);
+    expect(req.observedKey).toBe('user:resolved-by-oxy');
+  });
+
+  it('continues through the anonymous limiter if optional auth returns an error', () => {
+    const oxy = makeOxy((_req: Request, _res: Response, next: NextFunction) => {
+      next(new Error('token rejected'));
+    });
+    const req = makeRequest();
+    const next = jest.fn();
+
+    createOxyRateLimit(oxy, { authenticatedMax: 5000, anonymousMax: 600 })(
+      req,
+      {} as Response,
+      next,
+    );
+
+    expect(req.observedMax).toBe(600);
+    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/__tests__/safeFetch.test.ts

@@ -0,0 +1,232 @@
+import type { LookupAddress, LookupAllOptions, LookupOneOptions } from 'node:dns';
+import type { LookupFunction } from 'node:net';
+
+// Mock node:dns/promises so the static `import { lookup }` binding in safeFetch
+// is intercepted (spying on the namespace doesn't work — the binding is
+// resolved at module load, and the real `lookup` property is non-configurable).
+const mockDnsLookup = jest.fn();
+jest.mock('node:dns/promises', () => ({
+  lookup: (...args: unknown[]) => mockDnsLookup(...args),
+}));
+
+import {
+  assertSafePublicUrl,
+  isBlockedIp,
+} from '../safeFetch';
+
+beforeEach(() => {
+  mockDnsLookup.mockReset();
+});
+
+describe('@oxy.so/core/server safeFetch — isBlockedIp', () => {
+  it('blocks private / loopback / metadata / reserved IPv4 ranges', () => {
+    const blocked = [
+      '127.0.0.1', // loopback
+      '10.0.0.1', // RFC1918
+      '10.255.255.255',
+      '172.16.0.1', // RFC1918
+      '172.31.255.255',
+      '192.168.1.1', // RFC1918
+      '169.254.169.254', // cloud metadata
+      '169.254.0.1', // link-local
+      '100.64.0.1', // CGNAT
+      '0.0.0.0', // this network
+      '224.0.0.1', // multicast
+      '255.255.255.255', // broadcast
+      '198.18.0.1', // benchmarking
+    ];
+    for (const ip of blocked) {
+      expect(isBlockedIp(ip)).toBe(true);
+    }
+  });
+
+  it('blocks loopback / ULA / link-local IPv6 ranges and IPv4-mapped internals', () => {
+    const blocked = [
+      '::1', // loopback
+      '::', // unspecified
+      'fc00::1', // unique local
+      'fe80::1', // link-local
+      'ff02::1', // multicast
+      '::ffff:127.0.0.1', // IPv4-mapped loopback
+      '::ffff:169.254.169.254', // IPv4-mapped metadata
+    ];
+    for (const ip of blocked) {
+      expect(isBlockedIp(ip)).toBe(true);
+    }
+  });
+
+  it('allows genuine public IPs', () => {
+    expect(isBlockedIp('1.1.1.1')).toBe(false);
+    expect(isBlockedIp('8.8.8.8')).toBe(false);
+    expect(isBlockedIp('93.184.216.34')).toBe(false); // example.com historical
+    expect(isBlockedIp('2606:4700:4700::1111')).toBe(false); // public IPv6
+  });
+
+  it('fails closed for non-IP literals', () => {
+    expect(isBlockedIp('not-an-ip')).toBe(true);
+    expect(isBlockedIp('')).toBe(true);
+  });
+});
+
+describe('@oxy.so/core/server safeFetch — assertSafePublicUrl', () => {
+  it('rejects literal private / metadata IP URLs without any DNS', async () => {
+    const cases: Array<[string, RegExp]> = [
+      ['http://169.254.169.254/latest/meta-data/', /blocked range/],
+      ['http://127.0.0.1/', /blocked range/],
+      ['http://10.0.0.1/', /blocked range/],
+      ['http://192.168.0.1/', /blocked range/],
+      ['http://[::1]/', /blocked range/],
+    ];
+    for (const [url, reason] of cases) {
+      const result = await assertSafePublicUrl(url);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.reason).toMatch(reason);
+    }
+  });
+
+  it('rejects blocked hostnames before resolving', async () => {
+    const result = await assertSafePublicUrl('http://localhost/');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe('blocked hostname');
+  });
+
+  it('rejects ambiguous numeric host forms before touching DNS', async () => {
+    for (const url of [
+      'http://2130706433/', // decimal 127.0.0.1
+      'http://0x7f.1/',
+      'http://0177.0.0.1/',
+      'http://127.1/',
+    ]) {
+      const result = await assertSafePublicUrl(url);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(['ambiguous numeric host', 'literal ip in blocked range']).toContain(result.reason);
+      }
+    }
+  });
+
+  it('rejects disallowed protocols, ports, credentials, and oversized URLs', async () => {
+    expect((await assertSafePublicUrl('ftp://example.com/')).ok).toBe(false);
+    expect((await assertSafePublicUrl('file:///etc/passwd')).ok).toBe(false);
+    expect((await assertSafePublicUrl('http://example.com:22/')).ok).toBe(false);
+    expect((await assertSafePublicUrl('http://user:pass@example.com/')).ok).toBe(false);
+    expect((await assertSafePublicUrl('not a url')).ok).toBe(false);
+    expect((await assertSafePublicUrl(`http://example.com/${'a'.repeat(3000)}`)).ok).toBe(false);
+    expect((await assertSafePublicUrl('')).ok).toBe(false);
+  });
+
+  it('allows a literal public IP URL and pins the connection IP/family (no DNS)', async () => {
+    const result = await assertSafePublicUrl('https://1.1.1.1/');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.ip).toBe('1.1.1.1');
+      expect(result.family).toBe(4);
+    }
+    expect(mockDnsLookup).not.toHaveBeenCalled();
+  });
+
+  it('rejects a public hostname that resolves into a blocked range (rebind defence)', async () => {
+    mockDnsLookup.mockResolvedValue([{ address: '10.0.0.5', family: 4 }]);
+    const result = await assertSafePublicUrl('https://attacker.example/');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe('hostname resolves to blocked range');
+    expect(mockDnsLookup).toHaveBeenCalledWith('attacker.example', { all: true });
+  });
+
+  it('rejects when ANY of multiple resolved records is internal', async () => {
+    mockDnsLookup.mockResolvedValue([
+      { address: '93.184.216.34', family: 4 }, // public
+      { address: '169.254.169.254', family: 4 }, // metadata smuggled in
+    ]);
+    const result = await assertSafePublicUrl('https://multi.example/');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe('hostname resolves to blocked range');
+  });
+
+  it('rejects when DNS resolution fails', async () => {
+    mockDnsLookup.mockRejectedValue(new Error('ENOTFOUND'));
+    const result = await assertSafePublicUrl('https://nope.example/');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toBe('dns resolution failed');
+  });
+
+  it('allows a public hostname resolving to public IPs and pins the first record', async () => {
+    mockDnsLookup.mockResolvedValue([
+      { address: '93.184.216.34', family: 4 },
+      { address: '93.184.216.35', family: 4 },
+    ]);
+    const result = await assertSafePublicUrl('https://example.com/');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.ip).toBe('93.184.216.34');
+      expect(result.family).toBe(4);
+    }
+  });
+});
+
+/**
+ * Bun {all:true} lookup gotcha — shape assertion.
+ *
+ * The pinned `lookup` in safeFetch MUST return `[{address,family}]` when called
+ * with `{ all: true }` (Bun calls lookup(host,{all:true},cb) then `.sort()`s the
+ * result — a single value makes that internal sort throw "results.sort is not a
+ * function"), and the `(err,address,family)` triple otherwise (Node). We
+ * reconstruct the exact closure shape here and assert both call modes.
+ *
+ * (A full real-https.request verification against Bun was performed out of band;
+ * this unit test guards the array-vs-triple contract under Jest/Node.)
+ */
+describe('@oxy.so/core/server safeFetch — pinned lookup {all:true} contract', () => {
+  function makePinnedLookup(pinnedIp: string, pinnedFamily: 4 | 6): LookupFunction {
+    return ((
+      _hostname: string,
+      options: number | LookupOneOptions | LookupAllOptions,
+      callback: (
+        err: NodeJS.ErrnoException | null,
+        address: string | LookupAddress[],
+        family?: number,
+      ) => void,
+    ): void => {
+      const wantsAll = typeof options === 'object' && options !== null && options.all === true;
+      if (wantsAll) {
+        callback(null, [{ address: pinnedIp, family: pinnedFamily }]);
+      } else {
+        callback(null, pinnedIp, pinnedFamily);
+      }
+    }) as unknown as LookupFunction;
+  }
+
+  it('returns an ARRAY of {address,family} for {all:true} (sortable, no throw)', (done) => {
+    const lookup = makePinnedLookup('93.184.216.34', 4);
+    (lookup as unknown as (
+      h: string,
+      o: LookupAllOptions,
+      cb: (e: NodeJS.ErrnoException | null, a: LookupAddress[]) => void,
+    ) => void)(
+      'example.com',
+      { all: true } as LookupAllOptions,
+      (err, address) => {
+        expect(err).toBeNull();
+        expect(Array.isArray(address)).toBe(true);
+        // The address array is what Bun internally `.sort()`s — must be sortable.
+        expect(() => (address as LookupAddress[]).sort()).not.toThrow();
+        expect(address).toEqual([{ address: '93.184.216.34', family: 4 }]);
+        done();
+      },
+    );
+  });
+
+  it('returns the (address,family) triple for the non-all (Node) form', (done) => {
+    const lookup = makePinnedLookup('93.184.216.34', 4);
+    (lookup as unknown as (
+      h: string,
+      o: LookupOneOptions,
+      cb: (e: NodeJS.ErrnoException | null, a: string, f: number) => void,
+    ) => void)('example.com', {} as LookupOneOptions, (err, address, family) => {
+      expect(err).toBeNull();
+      expect(address).toBe('93.184.216.34');
+      expect(family).toBe(4);
+      done();
+    });
+  });
+});