SnowLuma/packages/core/tests/webui-client-ip.test.ts

import { describe, expect, it } from 'vitest';
import {
  describeTrustProxy,
  isLoopbackClientIp,
  parseTrustProxy,
  pickClientIp,
  type TrustProxyMode,
} from '../src/webui/client-ip';

describe('isLoopbackClientIp', () => {
  it.each(['127.0.0.1', '127.0.0.2', '::1', '0:0:0:0:0:0:0:1', '::ffff:127.0.0.9'])(
    'accepts loopback address %s',
    (address) => expect(isLoopbackClientIp(address)).toBe(true),
  );

  it.each(['', 'localhost', '0.0.0.0', '192.168.1.2', '::ffff:192.168.1.2'])(
    'rejects non-loopback or unverified address %s',
    (address) => expect(isLoopbackClientIp(address)).toBe(false),
  );
});

function mockCtx(headers: Record<string, string> = {}) {
  return {
    req: {
      header: (name: string) => headers[name.toLowerCase()],
    },
  } as unknown as Parameters<typeof pickClientIp>[0];
}

describe('parseTrustProxy', () => {
  it('treats empty / unset as none (safe default)', () => {
    expect(parseTrustProxy(undefined)).toEqual({ kind: 'none' });
    expect(parseTrustProxy('')).toEqual({ kind: 'none' });
    expect(parseTrustProxy('   ')).toEqual({ kind: 'none' });
  });

  it('recognises "1" / "true" / "all" as full trust', () => {
    expect(parseTrustProxy('1')).toEqual({ kind: 'all' });
    expect(parseTrustProxy('true')).toEqual({ kind: 'all' });
    expect(parseTrustProxy('ALL')).toEqual({ kind: 'all' });
  });

  it('recognises "loopback" case-insensitively', () => {
    expect(parseTrustProxy('Loopback')).toEqual({ kind: 'loopback' });
  });

  it('parses a comma-separated IP list', () => {
    const mode = parseTrustProxy('10.0.0.1, 192.168.1.5,  ');
    expect(mode.kind).toBe('ip-list');
    if (mode.kind !== 'ip-list') throw new Error('unreachable');
    expect([...mode.ips].sort()).toEqual(['10.0.0.1', '192.168.1.5']);
  });
});

describe('pickClientIp', () => {
  const xff = { 'x-forwarded-for': '203.0.113.7, 10.0.0.1' };
  const realIp = { 'x-real-ip': '203.0.113.42' };
  const both = { ...xff, ...realIp };

  it('returns socket peer and IGNORES headers when trust=none (default)', () => {
    const mode: TrustProxyMode = { kind: 'none' };
    expect(pickClientIp(mockCtx(both), mode, () => '198.51.100.9')).toBe('198.51.100.9');
  });

  it('honors X-Real-IP first, then XFF first hop, when trust=all', () => {
    const mode: TrustProxyMode = { kind: 'all' };
    expect(pickClientIp(mockCtx(both), mode, () => '10.0.0.1')).toBe('203.0.113.42');
    expect(pickClientIp(mockCtx(xff), mode, () => '10.0.0.1')).toBe('203.0.113.7');
  });

  it('falls back to socket peer when trust=all but no headers present', () => {
    const mode: TrustProxyMode = { kind: 'all' };
    expect(pickClientIp(mockCtx({}), mode, () => '10.0.0.1')).toBe('10.0.0.1');
  });

  it('trust=loopback honors headers only when socket is loopback', () => {
    const mode: TrustProxyMode = { kind: 'loopback' };
    expect(pickClientIp(mockCtx(both), mode, () => '127.0.0.1')).toBe('203.0.113.42');
    expect(pickClientIp(mockCtx(both), mode, () => '::1')).toBe('203.0.113.42');
    expect(pickClientIp(mockCtx(both), mode, () => '::ffff:127.0.0.1')).toBe('203.0.113.42');
    // Non-loopback peer → headers ignored, socket wins.
    expect(pickClientIp(mockCtx(both), mode, () => '10.0.0.1')).toBe('10.0.0.1');
  });

  it('trust=ip-list honors headers only when socket is in the list', () => {
    const mode: TrustProxyMode = { kind: 'ip-list', ips: new Set(['10.0.0.1', '10.0.0.2']) };
    expect(pickClientIp(mockCtx(both), mode, () => '10.0.0.2')).toBe('203.0.113.42');
    expect(pickClientIp(mockCtx(both), mode, () => '10.0.0.9')).toBe('10.0.0.9');
  });

  it('survives a socket resolver that throws', () => {
    const mode: TrustProxyMode = { kind: 'none' };
    expect(pickClientIp(mockCtx({}), mode, () => { throw new Error('boom'); })).toBe('127.0.0.1');
  });

  it('can fail closed when a security decision cannot resolve the socket peer', () => {
    const mode: TrustProxyMode = { kind: 'none' };
    expect(pickClientIp(mockCtx({}), mode, () => { throw new Error('boom'); }, '')).toBe('');
  });

  it('does not trust forwarded headers when the socket peer is unknown', () => {
    const mode: TrustProxyMode = { kind: 'all' };
    expect(
      pickClientIp(
        mockCtx({ 'x-real-ip': '127.0.0.1' }),
        mode,
        () => { throw new Error('boom'); },
        '',
      ),
    ).toBe('');
  });
});

describe('describeTrustProxy', () => {
  it('renders each mode in a recognisable form for the boot log', () => {
    expect(describeTrustProxy({ kind: 'none' })).toContain('socket peer');
    expect(describeTrustProxy({ kind: 'all' })).toContain('any peer');
    expect(describeTrustProxy({ kind: 'loopback' })).toContain('loopback');
    expect(describeTrustProxy({ kind: 'ip-list', ips: new Set(['10.0.0.1']) }))
      .toContain('10.0.0.1');
  });
});