refactor progress

packages/ip_utils/src/ClientIp.tsx

@@ -0,0 +1,167 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {parseIpAddress} from '@fluxer/ip_utils/src/IpAddress';
+
+export interface ClientIpExtractionOptions {
+	trustCfConnectingIp?: boolean;
+}
+
+export type ClientIpSource = 'cf-connecting-ip' | 'x-forwarded-for';
+
+export interface ExtractedClientIp {
+	ip: string;
+	source: ClientIpSource;
+}
+
+export interface HeadersLike {
+	[key: string]: string | Array<string> | undefined;
+}
+
+export class MissingClientIpError extends Error {
+	constructor() {
+		super('X-Forwarded-For header is required');
+		this.name = 'MissingClientIpError';
+	}
+}
+
+interface HeaderReader {
+	get(name: string): string | null;
+}
+
+function toStringHeaderValue(value: string | Array<string> | null | undefined): string | null {
+	if (Array.isArray(value)) {
+		const first = value[0];
+		return typeof first === 'string' ? first : null;
+	}
+	return typeof value === 'string' ? value : null;
+}
+
+function parseSingleIpHeader(value: string | null): string | null {
+	if (value === null) {
+		return null;
+	}
+
+	const trimmed = value.trim();
+	if (!trimmed) {
+		return null;
+	}
+
+	const parsed = parseIpAddress(trimmed);
+	return parsed?.normalized ?? null;
+}
+
+function parseForwardedForHeader(value: string | null): string | null {
+	if (value === null) {
+		return null;
+	}
+
+	const [firstCandidate] = value.split(',', 1);
+	if (!firstCandidate) {
+		return null;
+	}
+
+	return parseSingleIpHeader(firstCandidate);
+}
+
+function createRequestHeaderReader(request: Request): HeaderReader {
+	return {
+		get: (name: string): string | null => {
+			return request.headers.get(name);
+		},
+	};
+}
+
+function getHeaderValue(headers: HeadersLike, name: string): string | null {
+	const lowerName = name.toLowerCase();
+	const directMatch = toStringHeaderValue(headers[lowerName]);
+	if (directMatch !== null) {
+		return directMatch;
+	}
+
+	for (const [key, value] of Object.entries(headers)) {
+		if (key.toLowerCase() === lowerName) {
+			return toStringHeaderValue(value);
+		}
+	}
+
+	return null;
+}
+
+function createNodeHeaderReader(headers: HeadersLike): HeaderReader {
+	return {
+		get: (name: string): string | null => {
+			return getHeaderValue(headers, name);
+		},
+	};
+}
+
+function extractClientIpDetailsFromReader(
+	headerReader: HeaderReader,
+	options?: ClientIpExtractionOptions,
+): ExtractedClientIp | null {
+	if (options?.trustCfConnectingIp) {
+		const cfConnectingIp = parseSingleIpHeader(headerReader.get('cf-connecting-ip'));
+		if (cfConnectingIp) {
+			return {
+				ip: cfConnectingIp,
+				source: 'cf-connecting-ip',
+			};
+		}
+	}
+
+	const xForwardedFor = parseForwardedForHeader(headerReader.get('x-forwarded-for'));
+	if (xForwardedFor) {
+		return {
+			ip: xForwardedFor,
+			source: 'x-forwarded-for',
+		};
+	}
+
+	return null;
+}
+
+export function extractClientIpDetails(req: Request, options?: ClientIpExtractionOptions): ExtractedClientIp | null {
+	return extractClientIpDetailsFromReader(createRequestHeaderReader(req), options);
+}
+
+export function extractClientIp(req: Request, options?: ClientIpExtractionOptions): string | null {
+	const extracted = extractClientIpDetails(req, options);
+	return extracted?.ip ?? null;
+}
+
+export function requireClientIp(req: Request, options?: ClientIpExtractionOptions): string {
+	const ip = extractClientIp(req, options);
+	if (!ip) {
+		throw new MissingClientIpError();
+	}
+	return ip;
+}
+
+export function extractClientIpDetailsFromHeaders(
+	headers: HeadersLike,
+	options?: ClientIpExtractionOptions,
+): ExtractedClientIp | null {
+	return extractClientIpDetailsFromReader(createNodeHeaderReader(headers), options);
+}
+
+export function extractClientIpFromHeaders(headers: HeadersLike, options?: ClientIpExtractionOptions): string | null {
+	const extracted = extractClientIpDetailsFromHeaders(headers, options);
+	return extracted?.ip ?? null;
+}

packages/ip_utils/src/IpAddress.tsx

@@ -0,0 +1,101 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {isIPv4, isIPv6} from 'node:net';
+
+export type IpAddressFamily = 'ipv4' | 'ipv6';
+
+export interface ParsedIpAddress {
+	raw: string;
+	normalized: string;
+	family: IpAddressFamily;
+}
+
+function stripIpv6Brackets(value: string): string {
+	if (value.startsWith('[') && value.endsWith(']')) {
+		return value.slice(1, -1);
+	}
+	return value;
+}
+
+function stripIpv6ZoneIdentifier(value: string): string {
+	const zoneIndex = value.indexOf('%');
+	if (zoneIndex === -1) {
+		return value;
+	}
+
+	const addressPart = value.slice(0, zoneIndex);
+	if (!addressPart.includes(':')) {
+		return value;
+	}
+
+	return addressPart;
+}
+
+function normalizeIpv6(value: string): string {
+	if (!isIPv6(value)) {
+		return value;
+	}
+
+	try {
+		const hostname = new URL(`http://[${value}]`).hostname;
+		if (hostname.startsWith('[') && hostname.endsWith(']')) {
+			return hostname.slice(1, -1);
+		}
+		return hostname;
+	} catch {
+		return value;
+	}
+}
+
+function getAddressFamily(value: string): IpAddressFamily | null {
+	if (isIPv4(value)) {
+		return 'ipv4';
+	}
+	if (isIPv6(value)) {
+		return 'ipv6';
+	}
+	return null;
+}
+
+export function normalizeIpString(value: string): string {
+	const trimmed = value.trim();
+	const withoutBrackets = stripIpv6Brackets(trimmed);
+	const withoutZone = stripIpv6ZoneIdentifier(withoutBrackets);
+	return normalizeIpv6(withoutZone);
+}
+
+export function parseIpAddress(value: string): ParsedIpAddress | null {
+	const normalized = normalizeIpString(value);
+	const family = getAddressFamily(normalized);
+
+	if (!family) {
+		return null;
+	}
+
+	return {
+		raw: value,
+		normalized,
+		family,
+	};
+}
+
+export function isValidIp(value: string): boolean {
+	return parseIpAddress(value) !== null;
+}

packages/ip_utils/src/__tests__/ClientIp.test.tsx

@@ -0,0 +1,163 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {
+	extractClientIp,
+	extractClientIpDetails,
+	extractClientIpDetailsFromHeaders,
+	extractClientIpFromHeaders,
+	MissingClientIpError,
+	requireClientIp,
+} from '@fluxer/ip_utils/src/ClientIp';
+import {describe, expect, it} from 'vitest';
+
+describe('extractClientIp', () => {
+	it('extracts first x-forwarded-for entry', () => {
+		const request = new Request('http://example.com', {
+			headers: {'X-Forwarded-For': '192.168.1.1, 10.0.0.1'},
+		});
+
+		expect(extractClientIp(request)).toBe('192.168.1.1');
+	});
+
+	it('normalizes bracketed and zoned ipv6 from x-forwarded-for', () => {
+		const request = new Request('http://example.com', {
+			headers: {'X-Forwarded-For': '[fe80::1%eth0]'},
+		});
+
+		expect(extractClientIp(request)).toBe('fe80::1');
+	});
+
+	it('uses cf-connecting-ip when trusted', () => {
+		const request = new Request('http://example.com', {
+			headers: {
+				'Cf-Connecting-Ip': '203.0.113.50',
+				'X-Forwarded-For': '192.168.1.1',
+			},
+		});
+
+		expect(extractClientIp(request, {trustCfConnectingIp: true})).toBe('203.0.113.50');
+		expect(extractClientIp(request, {trustCfConnectingIp: false})).toBe('192.168.1.1');
+	});
+
+	it('falls back to x-forwarded-for when trusted cf-connecting-ip is invalid', () => {
+		const request = new Request('http://example.com', {
+			headers: {
+				'Cf-Connecting-Ip': 'not-an-ip',
+				'X-Forwarded-For': '192.168.1.1',
+			},
+		});
+
+		expect(extractClientIp(request, {trustCfConnectingIp: true})).toBe('192.168.1.1');
+	});
+
+	it('returns null for missing or invalid headers', () => {
+		expect(extractClientIp(new Request('http://example.com'))).toBeNull();
+		expect(
+			extractClientIp(
+				new Request('http://example.com', {
+					headers: {'X-Forwarded-For': ''},
+				}),
+			),
+		).toBeNull();
+		expect(
+			extractClientIp(
+				new Request('http://example.com', {
+					headers: {'X-Forwarded-For': ',192.168.1.1'},
+				}),
+			),
+		).toBeNull();
+		expect(
+			extractClientIp(
+				new Request('http://example.com', {
+					headers: {'X-Forwarded-For': 'not-an-ip'},
+				}),
+			),
+		).toBeNull();
+	});
+});
+
+describe('extractClientIpDetails', () => {
+	it('returns extracted ip and source', () => {
+		const xffRequest = new Request('http://example.com', {
+			headers: {'X-Forwarded-For': '192.168.1.1'},
+		});
+
+		expect(extractClientIpDetails(xffRequest)).toEqual({
+			ip: '192.168.1.1',
+			source: 'x-forwarded-for',
+		});
+
+		const cfRequest = new Request('http://example.com', {
+			headers: {
+				'Cf-Connecting-Ip': '203.0.113.50',
+				'X-Forwarded-For': '192.168.1.1',
+			},
+		});
+
+		expect(extractClientIpDetails(cfRequest, {trustCfConnectingIp: true})).toEqual({
+			ip: '203.0.113.50',
+			source: 'cf-connecting-ip',
+		});
+	});
+});
+
+describe('extractClientIpFromHeaders', () => {
+	it('extracts from node-style headers', () => {
+		const headers = {
+			'x-forwarded-for': '192.168.1.1, 10.0.0.1',
+		};
+
+		expect(extractClientIpFromHeaders(headers)).toBe('192.168.1.1');
+	});
+
+	it('supports case-insensitive keys and array values', () => {
+		const headers = {
+			'CF-CONNECTING-IP': ['203.0.113.50'],
+			'X-Forwarded-For': '192.168.1.1',
+		};
+
+		expect(extractClientIpFromHeaders(headers, {trustCfConnectingIp: true})).toBe('203.0.113.50');
+		expect(extractClientIpDetailsFromHeaders(headers, {trustCfConnectingIp: true})).toEqual({
+			ip: '203.0.113.50',
+			source: 'cf-connecting-ip',
+		});
+	});
+
+	it('returns null for invalid inputs', () => {
+		expect(extractClientIpFromHeaders({})).toBeNull();
+		expect(extractClientIpFromHeaders({'x-forwarded-for': 'not-an-ip'})).toBeNull();
+	});
+});
+
+describe('requireClientIp', () => {
+	it('returns ip when present', () => {
+		const request = new Request('http://example.com', {
+			headers: {'X-Forwarded-For': '192.168.1.1'},
+		});
+
+		expect(requireClientIp(request)).toBe('192.168.1.1');
+	});
+
+	it('throws typed error when missing', () => {
+		const request = new Request('http://example.com');
+		expect(() => requireClientIp(request)).toThrow(MissingClientIpError);
+		expect(() => requireClientIp(request)).toThrow('X-Forwarded-For header is required');
+	});
+});

packages/ip_utils/src/__tests__/IpAddress.test.tsx

@@ -0,0 +1,123 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {isValidIp, normalizeIpString, parseIpAddress} from '@fluxer/ip_utils/src/IpAddress';
+import {describe, expect, it} from 'vitest';
+
+describe('normalizeIpString', () => {
+	describe('ipv4 addresses', () => {
+		it('normalizes standard values', () => {
+			expect(normalizeIpString('192.168.1.1')).toBe('192.168.1.1');
+			expect(normalizeIpString('10.0.0.1')).toBe('10.0.0.1');
+			expect(normalizeIpString('172.16.0.1')).toBe('172.16.0.1');
+		});
+
+		it('trims whitespace', () => {
+			expect(normalizeIpString('  192.168.1.1  ')).toBe('192.168.1.1');
+			expect(normalizeIpString('\t10.0.0.1\n')).toBe('10.0.0.1');
+		});
+	});
+
+	describe('ipv6 addresses', () => {
+		it('normalizes standard values', () => {
+			expect(normalizeIpString('2001:db8::1')).toBe('2001:db8::1');
+			expect(normalizeIpString('::1')).toBe('::1');
+			expect(normalizeIpString('::')).toBe('::');
+		});
+
+		it('strips brackets and zone identifiers', () => {
+			expect(normalizeIpString('[2001:db8::1]')).toBe('2001:db8::1');
+			expect(normalizeIpString('fe80::1%eth0')).toBe('fe80::1');
+			expect(normalizeIpString('[fe80::1%en0]')).toBe('fe80::1');
+		});
+
+		it('normalizes case and compact form', () => {
+			expect(normalizeIpString('2001:DB8::1')).toBe('2001:db8::1');
+			expect(normalizeIpString('2001:0db8:0000:0000:0000:0000:0000:0001')).toBe('2001:db8::1');
+		});
+
+		it('normalizes ipv4-mapped ipv6 addresses', () => {
+			expect(normalizeIpString('::ffff:192.0.2.1')).toBe('::ffff:c000:201');
+		});
+	});
+
+	describe('edge cases', () => {
+		it('handles empty and invalid values', () => {
+			expect(normalizeIpString('')).toBe('');
+			expect(normalizeIpString('   ')).toBe('');
+			expect(normalizeIpString('not-an-ip')).toBe('not-an-ip');
+		});
+
+		it('does not strip brackets from host-port formats', () => {
+			expect(normalizeIpString('[2001:db8::1]:8080')).toBe('[2001:db8::1]:8080');
+		});
+
+		it('returns input value when url parsing fails', () => {
+			const OriginalURL = globalThis.URL;
+			globalThis.URL = class extends OriginalURL {
+				constructor(input: string | URL, base?: string | URL) {
+					if (typeof input === 'string' && input.includes('[2001:db8::ffff]')) {
+						throw new Error('Simulated URL parsing failure');
+					}
+					super(input, base);
+				}
+			} as typeof URL;
+
+			try {
+				expect(normalizeIpString('2001:db8::ffff')).toBe('2001:db8::ffff');
+			} finally {
+				globalThis.URL = OriginalURL;
+			}
+		});
+	});
+});
+
+describe('parseIpAddress', () => {
+	it('parses valid ip values', () => {
+		expect(parseIpAddress('192.168.1.1')).toEqual({
+			raw: '192.168.1.1',
+			normalized: '192.168.1.1',
+			family: 'ipv4',
+		});
+		expect(parseIpAddress('[2001:DB8::1]')).toEqual({
+			raw: '[2001:DB8::1]',
+			normalized: '2001:db8::1',
+			family: 'ipv6',
+		});
+	});
+
+	it('returns null for invalid values', () => {
+		expect(parseIpAddress('not-an-ip')).toBeNull();
+		expect(parseIpAddress('')).toBeNull();
+	});
+});
+
+describe('isValidIp', () => {
+	it('accepts valid values', () => {
+		expect(isValidIp('192.168.1.1')).toBe(true);
+		expect(isValidIp('[::1]')).toBe(true);
+		expect(isValidIp('fe80::1%eth0')).toBe(true);
+	});
+
+	it('rejects invalid values', () => {
+		expect(isValidIp('256.256.256.256')).toBe(false);
+		expect(isValidIp('gggg::1')).toBe(false);
+		expect(isValidIp('example.com')).toBe(false);
+	});
+});