@prosopo/ipinfo 0.2.14 → 0.2.15

package/src/IpInfoService.ts

@@ -0,0 +1,147 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { IPInfoResponse } from "@prosopo/types";
+import { IpapiBackend } from "./backends/ipapi.js";
+import { MaxMindBackend } from "./backends/maxmind.js";
+import type { IIpInfoService, IpInfoServiceConfig } from "./types.js";
+
+/**
+ * Returns true for loopback, link-local, and private-range IPs that will
+ * never yield useful geolocation or threat data from any backend.
+ */
+function isNonRoutable(ip: string): boolean {
+	// Strip IPv4-mapped IPv6 prefix (::ffff:127.0.0.1 -> 127.0.0.1)
+	const normalized = ip.replace(/^::ffff:/i, "");
+
+	// IPv4 private / loopback / link-local
+	if (
+		normalized.startsWith("127.") ||
+		normalized.startsWith("10.") ||
+		normalized.startsWith("192.168.") ||
+		normalized.startsWith("169.254.") ||
+		normalized === "0.0.0.0"
+	) {
+		return true;
+	}
+
+	// 172.16.0.0 – 172.31.255.255
+	if (normalized.startsWith("172.")) {
+		const second = Number.parseInt(normalized.split(".")[1] ?? "", 10);
+		if (second >= 16 && second <= 31) return true;
+	}
+
+	// IPv6 loopback
+	if (normalized === "::1" || normalized === "::") return true;
+
+	// IPv6 ULA (fc00::/7 — covers fc00:: through fdff::)
+	if (/^f[cd]/i.test(normalized)) return true;
+
+	// IPv6 link-local (fe80::/10)
+	if (/^fe[89ab]/i.test(normalized)) return true;
+
+	return false;
+}
+
+export class IpInfoService implements IIpInfoService {
+	private maxmindBackend: MaxMindBackend | null = null;
+	private ipapiBackend: IpapiBackend | null = null;
+	private config: IpInfoServiceConfig;
+
+	constructor(config: IpInfoServiceConfig) {
+		this.config = config;
+
+		if (config.maxmindCityDbPath || config.maxmindAsnDbPath) {
+			this.maxmindBackend = new MaxMindBackend({
+				cityDbPath: config.maxmindCityDbPath,
+				asnDbPath: config.maxmindAsnDbPath,
+				logger: config.logger,
+			});
+		}
+
+		if (config.ipapiUrl) {
+			this.ipapiBackend = new IpapiBackend({
+				baseUrl: config.ipapiUrl,
+				apiKey: config.ipapiKey,
+				logger: config.logger,
+			});
+		}
+	}
+
+	async initialize(): Promise<void> {
+		if (this.maxmindBackend) {
+			await this.maxmindBackend.initialize();
+		}
+
+		this.config.logger?.info(() => ({
+			msg: "IpInfoService initialized",
+			data: {
+				maxmindAvailable: this.maxmindBackend?.isAvailable() ?? false,
+				ipapiAvailable: this.ipapiBackend?.isAvailable() ?? false,
+			},
+		}));
+	}
+
+	isAvailable(): boolean {
+		return (
+			(this.maxmindBackend?.isAvailable() ?? false) ||
+			(this.ipapiBackend?.isAvailable() ?? false)
+		);
+	}
+
+	async lookup(ip: string): Promise<IPInfoResponse> {
+		if (isNonRoutable(ip)) {
+			return {
+				isValid: false,
+				error: "Non-routable IP address",
+				ip,
+			};
+		}
+
+		// Prefer ipapi.is when available (richer threat data)
+		if (this.ipapiBackend?.isAvailable()) {
+			const result = await this.ipapiBackend.lookup(ip);
+			if (result.isValid) {
+				return result;
+			}
+
+			// ipapi.is failed, fall back to MaxMind if available
+			this.config.logger?.debug(() => ({
+				msg: "ipapi.is lookup failed, falling back to MaxMind",
+				data: {
+					ip,
+					error: "error" in result ? result.error : "unknown",
+				},
+			}));
+
+			if (this.maxmindBackend?.isAvailable()) {
+				return this.maxmindBackend.lookup(ip);
+			}
+
+			// Return the ipapi error if no MaxMind fallback
+			return result;
+		}
+
+		// MaxMind only
+		if (this.maxmindBackend?.isAvailable()) {
+			return this.maxmindBackend.lookup(ip);
+		}
+
+		return {
+			isValid: false,
+			error: "No IP info backend available",
+			ip,
+		};
+	}
+}

package/src/backends/ipapi.ts

@@ -0,0 +1,148 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Logger } from "@prosopo/logger";
+import type {
+	IPApiResponse,
+	IPInfoResponse,
+	IPInfoResult,
+} from "@prosopo/types";
+
+const TIMEOUT_MS = 700;
+
+export interface IpapiBackendConfig {
+	baseUrl: string;
+	apiKey?: string;
+	logger?: Logger;
+}
+
+export class IpapiBackend {
+	private config: IpapiBackendConfig;
+
+	constructor(config: IpapiBackendConfig) {
+		this.config = config;
+	}
+
+	isAvailable(): boolean {
+		return Boolean(this.config.baseUrl);
+	}
+
+	async lookup(ip: string): Promise<IPInfoResponse> {
+		try {
+			if (!ip || typeof ip !== "string") {
+				return {
+					isValid: false,
+					error: "Invalid IP address provided",
+					ip: ip || "undefined",
+				};
+			}
+
+			const body: { q: string; key?: string } = { q: ip };
+			if (this.config.apiKey) {
+				body.key = this.config.apiKey;
+			}
+
+			const controller = new AbortController();
+			const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+			try {
+				const response = await fetch(this.config.baseUrl, {
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						Accept: "application/json",
+					},
+					body: JSON.stringify(body),
+					signal: controller.signal,
+				});
+
+				clearTimeout(timeoutId);
+
+				if (!response.ok) {
+					return {
+						isValid: false,
+						error: `API request failed with status ${response.status}: ${response.statusText}`,
+						ip,
+					};
+				}
+
+				const data: IPApiResponse = (await response.json()) as IPApiResponse;
+
+				if (data.is_bogon) {
+					return {
+						isValid: false,
+						error: "IP address is bogon (non-routable)",
+						ip,
+					};
+				}
+
+				const result: IPInfoResult = {
+					ip: data.ip,
+					isValid: true,
+
+					isVPN: data.is_vpn,
+					isTor: data.is_tor,
+					isProxy: data.is_proxy,
+					isDatacenter: data.is_datacenter,
+					isAbuser: data.is_abuser,
+					isMobile: data.is_mobile,
+					isSatellite: data.is_satellite,
+					isCrawler: data.is_crawler,
+					providerName: data.company?.name || data.datacenter?.datacenter,
+					providerType: data.company?.type || data.asn?.type,
+					asnNumber: data.asn?.asn,
+					asnOrganization: data.asn?.org,
+
+					country: data.location?.country,
+					countryCode: data.location?.country_code,
+					region: data.location?.state,
+					city: data.location?.city,
+					latitude: data.location?.latitude,
+					longitude: data.location?.longitude,
+					timezone: data.location?.timezone,
+
+					vpnService: data.vpn?.service,
+					vpnType: data.vpn?.type,
+
+					abuserScore: Number.parseFloat(
+						data.asn?.abuser_score.split(" ")[0] || "0",
+					),
+					companyAbuserScore: Number.parseFloat(
+						data.company?.abuser_score.split(" ")[0] || "0",
+					),
+				};
+
+				return result;
+			} catch (fetchError) {
+				clearTimeout(timeoutId);
+
+				if (fetchError instanceof Error && fetchError.name === "AbortError") {
+					return {
+						isValid: false,
+						error: `Request timed out after ${TIMEOUT_MS}ms`,
+						ip,
+					};
+				}
+
+				throw fetchError;
+			}
+		} catch (error) {
+			return {
+				isValid: false,
+				error: `Network or parsing error: ${error instanceof Error ? error.message : String(error)}`,
+				ip,
+			};
+		}
+	}
+}

package/src/backends/maxmind.ts

@@ -0,0 +1,222 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Asn, City, ReaderModel } from "@maxmind/geoip2-node";
+import type { Logger } from "@prosopo/logger";
+import type { IPInfoResponse, IPInfoResult } from "@prosopo/types";
+
+export interface MaxMindBackendConfig {
+	cityDbPath?: string;
+	asnDbPath?: string;
+	logger?: Logger;
+}
+
+export class MaxMindBackend {
+	private cityReader: ReaderModel | null = null;
+	private asnReader: ReaderModel | null = null;
+	private config: MaxMindBackendConfig;
+
+	constructor(config: MaxMindBackendConfig) {
+		this.config = config;
+	}
+
+	async initialize(): Promise<void> {
+		const { Reader } = await import("@maxmind/geoip2-node");
+
+		if (this.config.cityDbPath) {
+			try {
+				this.cityReader = await Reader.open(this.config.cityDbPath);
+				this.config.logger?.info(() => ({
+					msg: "MaxMind City reader initialized",
+					data: { dbPath: this.config.cityDbPath },
+				}));
+			} catch (error) {
+				this.config.logger?.warn(() => ({
+					msg: "Failed to initialize MaxMind City reader",
+					err: error,
+					data: { dbPath: this.config.cityDbPath },
+				}));
+			}
+		}
+
+		if (this.config.asnDbPath) {
+			try {
+				this.asnReader = await Reader.open(this.config.asnDbPath);
+				this.config.logger?.info(() => ({
+					msg: "MaxMind ASN reader initialized",
+					data: { dbPath: this.config.asnDbPath },
+				}));
+			} catch (error) {
+				this.config.logger?.warn(() => ({
+					msg: "Failed to initialize MaxMind ASN reader",
+					err: error,
+					data: { dbPath: this.config.asnDbPath },
+				}));
+			}
+		}
+	}
+
+	isAvailable(): boolean {
+		return this.cityReader !== null || this.asnReader !== null;
+	}
+
+	async lookup(ip: string): Promise<IPInfoResponse> {
+		if (!this.isAvailable()) {
+			return {
+				isValid: false,
+				error: "MaxMind readers not initialized",
+				ip,
+			};
+		}
+
+		try {
+			let cityData: City | undefined;
+			let asnData: Asn | undefined;
+
+			if (this.cityReader) {
+				try {
+					cityData = this.cityReader.city(ip);
+				} catch (error) {
+					this.config.logger?.debug(() => ({
+						msg: "MaxMind City lookup failed",
+						data: { ip },
+						err: error,
+					}));
+				}
+			}
+
+			if (this.asnReader) {
+				try {
+					asnData = this.asnReader.asn(ip);
+				} catch (error) {
+					this.config.logger?.debug(() => ({
+						msg: "MaxMind ASN lookup failed",
+						data: { ip },
+						err: error,
+					}));
+				}
+			}
+
+			if (!cityData && !asnData) {
+				return {
+					isValid: false,
+					error: "No MaxMind data available for IP",
+					ip,
+				};
+			}
+
+			const result: IPInfoResult = {
+				ip,
+				isValid: true,
+
+				// Threat indicators - GeoLite2 free DBs do not populate these
+				isVPN: cityData?.traits?.isAnonymousVpn ?? false,
+				isTor: cityData?.traits?.isTorExitNode ?? false,
+				isProxy:
+					(cityData?.traits?.isPublicProxy ?? false) ||
+					(cityData?.traits?.isResidentialProxy ?? false),
+				isDatacenter: cityData?.traits?.isHostingProvider ?? false,
+				isAbuser: false,
+				isMobile: false,
+				isSatellite: cityData?.traits?.isSatelliteProvider ?? false,
+				isCrawler: false,
+
+				// Geolocation from City DB
+				country: cityData?.country?.names?.en,
+				countryCode: cityData?.country?.isoCode,
+				region: cityData?.subdivisions?.[0]?.names?.en,
+				city: cityData?.city?.names?.en,
+				latitude: cityData?.location?.latitude,
+				longitude: cityData?.location?.longitude,
+				timezone: cityData?.location?.timeZone,
+
+				// ASN info - prefer City DB traits, fall back to ASN DB
+				asnNumber:
+					cityData?.traits?.autonomousSystemNumber ??
+					asnData?.autonomousSystemNumber,
+				asnOrganization:
+					cityData?.traits?.autonomousSystemOrganization ??
+					asnData?.autonomousSystemOrganization,
+
+				// Provider info from ASN
+				providerName:
+					cityData?.traits?.autonomousSystemOrganization ??
+					asnData?.autonomousSystemOrganization,
+				providerType: mapUserType(cityData?.traits?.userType),
+			};
+
+			return result;
+		} catch (error) {
+			return {
+				isValid: false,
+				error: `MaxMind lookup error: ${error instanceof Error ? error.message : String(error)}`,
+				ip,
+			};
+		}
+	}
+}
+
+type MaxMindUserType =
+	| "business"
+	| "cafe"
+	| "cellular"
+	| "college"
+	| "consumer_privacy_network"
+	| "content_delivery_network"
+	| "dialup"
+	| "government"
+	| "hosting"
+	| "library"
+	| "military"
+	| "residential"
+	| "router"
+	| "school"
+	| "search_engine_spider"
+	| "traveler";
+
+type ProviderType =
+	| "hosting"
+	| "education"
+	| "government"
+	| "banking"
+	| "business"
+	| "isp";
+
+function mapUserType(
+	userType: MaxMindUserType | undefined,
+): ProviderType | undefined {
+	switch (userType) {
+		case "hosting":
+		case "content_delivery_network":
+			return "hosting";
+		case "college":
+		case "school":
+		case "library":
+			return "education";
+		case "government":
+		case "military":
+			return "government";
+		case "business":
+			return "business";
+		case "residential":
+		case "cellular":
+		case "dialup":
+		case "cafe":
+		case "traveler":
+		case "router":
+			return "isp";
+		default:
+			return undefined;
+	}
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export { IpInfoService } from "./IpInfoService.js";
+export type { IIpInfoService, IpInfoServiceConfig } from "./types.js";

package/src/types.ts

@@ -0,0 +1,30 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { Logger } from "@prosopo/logger";
+import type { IPInfoResponse } from "@prosopo/types";
+
+export interface IIpInfoService {
+	initialize(): Promise<void>;
+	lookup(ip: string): Promise<IPInfoResponse>;
+	isAvailable(): boolean;
+}
+
+export interface IpInfoServiceConfig {
+	maxmindCityDbPath?: string;
+	maxmindAsnDbPath?: string;
+	ipapiUrl?: string;
+	ipapiKey?: string;
+	logger?: Logger;
+}

package/tsconfig.cjs.json

@@ -0,0 +1,24 @@
+{
+	"extends": "../../tsconfig.cjs.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist/cjs"
+	},
+	"include": [
+		"./src/**/*.ts",
+		"./src/**/*.json",
+		"./src/**/*.d.ts",
+		"./src/**/*.tsx"
+	],
+	"references": [
+		{
+			"path": "../../dev/config/tsconfig.cjs.json"
+		},
+		{
+			"path": "../logger/tsconfig.cjs.json"
+		},
+		{
+			"path": "../types/tsconfig.cjs.json"
+		}
+	]
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"extends": "../../tsconfig.esm.json",
+	"compilerOptions": {
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"include": [
+		"src",
+		"src/**/*.json",
+		"src/**/*.ts",
+		"src/**/*.tsx",
+		"src/**/*.d.ts"
+	],
+	"references": [
+		{
+			"path": "../../dev/config/tsconfig.json"
+		},
+		{
+			"path": "../logger"
+		},
+		{
+			"path": "../types"
+		}
+	]
+}