@prosopo/ipinfo 0.3.21 → 0.3.23

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/ipinfo",
-	"version": "0.3.21",
+	"version": "0.3.23",
 	"description": "IP information service with MaxMind and ipapi.is backends",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -28,18 +28,18 @@
 	},
 	"dependencies": {
 		"@maxmind/geoip2-node": "7.1.0",
-		"@prosopo/logger": "2.0.7",
-		"@prosopo/types": "5.5.3"
+		"@prosopo/logger": "2.0.9",
+		"@prosopo/types": "5.7.0"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.12",
+		"@prosopo/config": "3.3.14",
 		"@types/node": "22.10.2",
-		"@vitest/coverage-v8": "4.1.10",
+		"@vitest/coverage-v8": "4.1.11",
 		"del-cli": "6.0.0",
 		"tslib": "2.7.0",
 		"typescript": "5.6.2",
 		"vite": "8.1.5",
-		"vitest": "4.1.10"
+		"vitest": "4.1.11"
 	},
 	"license": "Apache-2.0",
 	"repository": {

package/src/backends/maxmind.ts

@@ -12,7 +12,7 @@
 // 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 { Asn, City, Country, ReaderModel } from "@maxmind/geoip2-node";
 import type { Logger } from "@prosopo/logger";
 import type { IPInfoResponse, IPInfoResult } from "@prosopo/types";
 
@@ -40,9 +40,29 @@ export interface MaxMindBackendConfig {
 	openReader?: OpenReader;
 }
 
+/**
+ * Which accessor the geo reader actually supports.
+ *
+ * `cityDbPath` is a path, not a promise of a City database — production points
+ * it at GeoLite2-Country.mmdb. `Reader.open()` accepts any valid .mmdb, so the
+ * reader opens and `isAvailable()` reports true, but `city()` checks
+ * `metadata.databaseType` and throws `BadMethodCallError` on every call. The
+ * result was a backend that claimed to be up and failed 100% of lookups —
+ * invisible until the ipapi.is sidecar it was meant to back up went down.
+ *
+ * `metadata` is not on `ReaderModel`'s public type, so the kind is latched
+ * lazily on the first `BadMethodCallError` rather than probed at open time.
+ * "unknown" only ever costs one extra throw for the process lifetime.
+ */
+type GeoReaderKind = "unknown" | "city" | "country";
+
+/** Thrown by geoip2-node when an accessor doesn't match the database type. */
+const BAD_METHOD_CALL_ERROR = "BadMethodCallError";
+
 export class MaxMindBackend {
 	private cityReader: ReaderModel | null = null;
 	private asnReader: ReaderModel | null = null;
+	private geoReaderKind: GeoReaderKind = "unknown";
 	private config: MaxMindBackendConfig;
 
 	constructor(config: MaxMindBackendConfig) {
@@ -100,17 +120,44 @@ export class MaxMindBackend {
 
 		try {
 			let cityData: City | undefined;
+			let countryData: Country | 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.geoReaderKind !== "country") {
+					try {
+						cityData = this.cityReader.city(ip);
+						this.geoReaderKind = "city";
+					} catch (error) {
+						if (isBadMethodCall(error)) {
+							// Not a City database. Latch so subsequent lookups go
+							// straight to country() instead of paying the throw.
+							this.geoReaderKind = "country";
+							this.config.logger?.warn(() => ({
+								msg: "MaxMind geo database is not a City database; falling back to country-level lookups",
+								data: { dbPath: this.config.cityDbPath },
+								err: error,
+							}));
+						} else {
+							this.config.logger?.debug(() => ({
+								msg: "MaxMind City lookup failed",
+								data: { ip },
+								err: error,
+							}));
+						}
+					}
+				}
+
+				if (this.geoReaderKind === "country") {
+					try {
+						countryData = this.cityReader.country(ip);
+					} catch (error) {
+						this.config.logger?.debug(() => ({
+							msg: "MaxMind Country lookup failed",
+							data: { ip },
+							err: error,
+						}));
+					}
 				}
 			}
 
@@ -126,7 +173,11 @@ export class MaxMindBackend {
 				}
 			}
 
-			if (!cityData && !asnData) {
+			// `City extends Country`, so everything below the city/subdivision/
+			// location fields reads off whichever one the database gave us.
+			const geoData: City | Country | undefined = cityData ?? countryData;
+
+			if (!geoData && !asnData) {
 				return {
 					isValid: false,
 					error: "No MaxMind data available for IP",
@@ -139,39 +190,40 @@ export class MaxMindBackend {
 				isValid: true,
 
 				// Threat indicators - GeoLite2 free DBs do not populate these
-				isVPN: cityData?.traits?.isAnonymousVpn ?? false,
-				isTor: cityData?.traits?.isTorExitNode ?? false,
+				isVPN: geoData?.traits?.isAnonymousVpn ?? false,
+				isTor: geoData?.traits?.isTorExitNode ?? false,
 				isProxy:
-					(cityData?.traits?.isPublicProxy ?? false) ||
-					(cityData?.traits?.isResidentialProxy ?? false),
-				isDatacenter: cityData?.traits?.isHostingProvider ?? false,
+					(geoData?.traits?.isPublicProxy ?? false) ||
+					(geoData?.traits?.isResidentialProxy ?? false),
+				isDatacenter: geoData?.traits?.isHostingProvider ?? false,
 				isAbuser: false,
 				isMobile: false,
-				isSatellite: cityData?.traits?.isSatelliteProvider ?? false,
+				isSatellite: geoData?.traits?.isSatelliteProvider ?? false,
 				isCrawler: false,
 
-				// Geolocation from City DB
-				country: cityData?.country?.names?.en,
-				countryCode: cityData?.country?.isoCode,
+				// Country is available from both database types; the rest needs a
+				// City database and stays undefined on a Country-only one.
+				country: geoData?.country?.names?.en,
+				countryCode: geoData?.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
+				// ASN info - prefer geo DB traits, fall back to ASN DB
 				asnNumber:
-					cityData?.traits?.autonomousSystemNumber ??
+					geoData?.traits?.autonomousSystemNumber ??
 					asnData?.autonomousSystemNumber,
 				asnOrganization:
-					cityData?.traits?.autonomousSystemOrganization ??
+					geoData?.traits?.autonomousSystemOrganization ??
 					asnData?.autonomousSystemOrganization,
 
 				// Provider info from ASN
 				providerName:
-					cityData?.traits?.autonomousSystemOrganization ??
+					geoData?.traits?.autonomousSystemOrganization ??
 					asnData?.autonomousSystemOrganization,
-				providerType: mapUserType(cityData?.traits?.userType),
+				providerType: mapUserType(geoData?.traits?.userType),
 			};
 
 			return result;
@@ -185,6 +237,14 @@ export class MaxMindBackend {
 	}
 }
 
+/**
+ * geoip2-node sets `name` on its error classes, so this survives the class
+ * identity being lost across the lazy `import()` in `openReaderFromFile`.
+ */
+function isBadMethodCall(error: unknown): boolean {
+	return error instanceof Error && error.name === BAD_METHOD_CALL_ERROR;
+}
+
 export type MaxMindUserType =
 	| "business"
 	| "cafe"

package/src/tests/maxmind.unit.test.ts

@@ -18,7 +18,7 @@
 // impossible to reach at all. The reader is therefore injected, and everything
 // the backend does with its output runs for real.
 
-import type { Asn, City, ReaderModel } from "@maxmind/geoip2-node";
+import type { Asn, City, Country, ReaderModel } from "@maxmind/geoip2-node";
 import type { IPInfoResult } from "@prosopo/types";
 import { describe, expect, it, vi } from "vitest";
 import {
@@ -31,9 +31,10 @@ const IP = "8.8.8.8";
 const CITY_DB = "/dbs/GeoLite2-City.mmdb";
 const ASN_DB = "/dbs/GeoLite2-ASN.mmdb";
 
-/** Builds a reader that answers city/asn lookups however the test needs. */
+/** Builds a reader that answers city/country/asn lookups however the test needs. */
 const reader = (behaviour: {
 	city?: () => City;
+	country?: () => Country;
 	asn?: () => Asn;
 }): ReaderModel => {
 	const notSupported = (): never => {
@@ -42,10 +43,24 @@ const reader = (behaviour: {
 	};
 	return {
 		city: behaviour.city ?? notSupported,
+		country: behaviour.country ?? notSupported,
 		asn: behaviour.asn ?? notSupported,
 	} as unknown as ReaderModel;
 };
 
+/**
+ * The error geoip2-node raises when an accessor doesn't match the opened
+ * database — `city()` against GeoLite2-Country, for instance. It is identified
+ * by `name`, so the name is what the fake sets.
+ */
+const badMethodCall = (): never => {
+	const error = new Error(
+		"The city() method cannot be used with the GeoLite2-Country database",
+	);
+	error.name = "BadMethodCallError";
+	throw error;
+};
+
 const cityData = (overrides: Partial<City> = {}): City =>
 	({
 		country: { isoCode: "US", names: { en: "United States" } },
@@ -60,6 +75,13 @@ const cityData = (overrides: Partial<City> = {}): City =>
 		...overrides,
 	}) as City;
 
+const countryData = (overrides: Partial<Country> = {}): Country =>
+	({
+		country: { isoCode: "US", names: { en: "United States" } },
+		traits: {},
+		...overrides,
+	}) as Country;
+
 const asnData = (overrides: Partial<Asn> = {}): Asn =>
 	({
 		autonomousSystemNumber: 15169,
@@ -547,6 +569,150 @@ describe("MaxMindBackend.lookup", () => {
 	});
 });
 
+describe("MaxMindBackend with a Country-only geo database", () => {
+	// Production points cityDbPath at GeoLite2-Country.mmdb (MAXMIND_DB_PATH).
+	// Reader.open accepts it, so isAvailable() reports true, but city() rejects
+	// the database type on every call. Before this was handled the backend
+	// answered "No MaxMind data available for IP" for every address — a fallback
+	// that looked healthy and had never once produced an answer.
+	const countryBackend = async (options: {
+		city?: () => City;
+		country?: () => Country;
+	}): Promise<MaxMindBackend> => {
+		const backend = new MaxMindBackend({
+			cityDbPath: CITY_DB,
+			openReader: opens({
+				city: reader({
+					city: options.city ?? badMethodCall,
+					country: options.country ?? ((): Country => countryData()),
+				}),
+			}),
+		});
+		await backend.initialize();
+		return backend;
+	};
+
+	it("answers from country() when city() rejects the database type", async () => {
+		const backend = await countryBackend({});
+
+		const result = expectValid(await backend.lookup(IP));
+
+		expect(result).toMatchObject({
+			ip: IP,
+			isValid: true,
+			country: "United States",
+			countryCode: "US",
+		});
+	});
+
+	it("leaves the city-only fields unset rather than inventing them", async () => {
+		// Country-level data is enough for geoblocking but cannot support the
+		// distance comparison, and consumers must be able to tell.
+		const backend = await countryBackend({});
+
+		const result = expectValid(await backend.lookup(IP));
+
+		expect(result.city).toBeUndefined();
+		expect(result.region).toBeUndefined();
+		expect(result.latitude).toBeUndefined();
+		expect(result.longitude).toBeUndefined();
+		expect(result.timezone).toBeUndefined();
+	});
+
+	it("still reads the traits the country record carries", async () => {
+		const backend = await countryBackend({
+			country: (): Country =>
+				countryData({
+					traits: {
+						isAnonymousVpn: true,
+						autonomousSystemNumber: 15169,
+						autonomousSystemOrganization: "Google LLC",
+					},
+				} as Partial<Country>),
+		});
+
+		const result = expectValid(await backend.lookup(IP));
+
+		expect(result.isVPN).toBe(true);
+		expect(result.asnNumber).toBe(15169);
+		expect(result.providerName).toBe("Google LLC");
+	});
+
+	it("stops calling city() once the database type is known", async () => {
+		// Constructing the rejection is the expensive part; paying it per request
+		// on every lookup for the life of the process is not acceptable.
+		const city = vi.fn(badMethodCall);
+		const backend = await countryBackend({ city });
+
+		await backend.lookup(IP);
+		await backend.lookup(IP);
+		await backend.lookup(IP);
+
+		expect(city).toHaveBeenCalledTimes(1);
+	});
+
+	it("warns once, naming the database, when it discovers the mismatch", async () => {
+		// Silent degradation is what let this sit unnoticed; the path an operator
+		// has to correct is in the payload.
+		const warn = vi.fn();
+		const backend = new MaxMindBackend({
+			cityDbPath: CITY_DB,
+			openReader: opens({
+				city: reader({
+					city: badMethodCall,
+					country: (): Country => countryData(),
+				}),
+			}),
+			logger: { warn, info: vi.fn(), debug: vi.fn() } as never,
+		});
+		await backend.initialize();
+
+		await backend.lookup(IP);
+		await backend.lookup(IP);
+
+		expect(warn).toHaveBeenCalledTimes(1);
+		type WarnPayload = { msg: string; data: { dbPath: string } };
+		const payload: WarnPayload = (
+			warn.mock.calls[0]?.[0] as () => WarnPayload
+		)();
+		expect(payload.msg).toBe(
+			"MaxMind geo database is not a City database; falling back to country-level lookups",
+		);
+		expect(payload.data.dbPath).toBe(CITY_DB);
+	});
+
+	it("reports no data when the country lookup finds nothing either", async () => {
+		const backend = await countryBackend({
+			country: (): never => {
+				throw new Error("address not found");
+			},
+		});
+
+		await expect(backend.lookup(IP)).resolves.toEqual({
+			isValid: false,
+			error: "No MaxMind data available for IP",
+			ip: IP,
+		});
+	});
+
+	it("never calls country() when the database really is a City database", async () => {
+		// The fallback must not become a second lookup on the happy path.
+		const country = vi.fn((): Country => countryData());
+		const backend = new MaxMindBackend({
+			cityDbPath: CITY_DB,
+			openReader: opens({
+				city: reader({ city: () => cityData(), country }),
+			}),
+		});
+		await backend.initialize();
+
+		await backend.lookup(IP);
+		await backend.lookup(IP);
+
+		expect(country).not.toHaveBeenCalled();
+	});
+});
+
 describe("MaxMindBackend default reader", () => {
 	it("does not throw when the real database file is missing", async () => {
 		// Exercises the un-injected path: the lazy import of the MaxMind reader