feat(geo): bundle GeoLite2-City and add an offline-first lookup path

Rewrites src/lib/geo.ts so lookupIpLocation reads from the bundled
MaxMind GeoLite2-City MMDB first and falls back to the existing
ipwho.is path only for IPs the offline DB cannot resolve. Adds a
sibling lookupIpAsn that returns { asn, carrier } from the
GeoLite2-ASN MMDB so the admin login-overview can grow a carrier
chip alongside the auth-provider chip.

The MMDB files are too large to vendor in git. scripts/fetch-geolite2.sh
downloads them at build time using a MaxMind license key; the
Dockerfile copies assets/geolite2/ into /opt/geolite2/. When the
license key is absent or the files are missing the image still
builds and the resolver falls back to ipwho.is (v1.4.26 behaviour).

GeoLite2 is CC BY-SA 4.0 — attribution lives on the new public
/about page and in docs/audit/v1427-summary.md.
This commit is contained in:
Marc-André Bombeck committed 2026-05-15 16:36:55 +02:00
1 parent 2c9d17c333
commit 50150e35ef
11 files changed
+834 -18

No files matched your search

+267
View File
@@ -0,0 +1,267 @@
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
/**
* v1.4.27 B3 — ASN + carrier lookup tests.
*
* The MaxMind GeoLite2-ASN MMDB is too large for the test fixtures
* directory (~10 MB) and shipping it would bloat git history. These
* tests mock `mmdb-lib` directly so the assertion focuses on the
* resolver contract:
*
* - Private / loopback IPs short-circuit to `null` without touching
* the reader.
* - A missing MMDB file (no offline DB on the host) yields `null`.
* - A row from the DB with both `autonomous_system_number` and
* `autonomous_system_organization` is folded into `{ asn, carrier }`.
* - Reader throws are swallowed (the helper is called from a
* fire-and-forget audit-log path; a thrown error would surface as
* an unhandled rejection).
* - The offline-first `lookupIpLocation` path picks the German city
* name first, English second, with the country ISO code from
* `country` or `registered_country`.
*
* The MMDB Reader is mocked once at the top of the file; per-test
* shape control happens through the `setReaderRow` + `setReaderThrows`
* helpers below. The `fs` stub is also installed module-wide so the
* lazy loader believes the DB exists.
*/
interface AsnRow {
autonomous_system_number?: number;
autonomous_system_organization?: string;
}
interface CityRow {
city?: { names?: Record<string, string> };
country?: { iso_code?: string };
registered_country?: { iso_code?: string };
}
// Test-time spy state — captured by the mocked Reader. The Reader
// constructor inspects the buffer header to decide whether it's
// serving City or ASN rows.
const readerState = {
city: null as ((ip: string) => CityRow | null) | null,
asn: null as ((ip: string) => AsnRow | null) | null,
cityThrows: false,
asnThrows: false,
cityExists: false,
asnExists: false,
};
vi.mock("mmdb-lib", () => ({
Reader: class {
private kind: "city" | "asn";
constructor(buf: Buffer) {
const head = buf.toString("utf-8", 0, 4);
this.kind = head === "city" ? "city" : "asn";
}
get(ip: string): AsnRow | CityRow | null {
if (this.kind === "asn") {
if (readerState.asnThrows) throw new Error("mmdb-asn boom");
return readerState.asn ? readerState.asn(ip) : null;
}
if (readerState.cityThrows) throw new Error("mmdb-city boom");
return readerState.city ? readerState.city(ip) : null;
}
},
}));
vi.mock("node:fs", async () => {
const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
const existsSync = (p: string) => {
if (p.endsWith("GeoLite2-City.mmdb")) return readerState.cityExists;
if (p.endsWith("GeoLite2-ASN.mmdb")) return readerState.asnExists;
return false;
};
const readFileSync = (p: string) => {
if (p.endsWith("GeoLite2-City.mmdb"))
return Buffer.from("city-mmdb-stub");
if (p.endsWith("GeoLite2-ASN.mmdb"))
return Buffer.from("asn-mmdb-stub");
throw new Error(`unexpected read ${p}`);
};
return {
...actual,
existsSync,
readFileSync,
default: { ...actual, existsSync, readFileSync },
};
});
const ORIGINAL_ENV = { ...process.env };
beforeEach(async () => {
process.env = { ...ORIGINAL_ENV };
delete process.env.IP_GEO_LOOKUP_DISABLED;
delete process.env.GEOLITE2_DIR;
readerState.city = null;
readerState.asn = null;
readerState.cityThrows = false;
readerState.asnThrows = false;
readerState.cityExists = false;
readerState.asnExists = false;
vi.resetModules();
// Reset the lazy cache so each test gets a fresh Reader load.
const mod = await import("../geo");
mod.__resetGeoLite2CacheForTests();
});
afterEach(() => {
process.env = ORIGINAL_ENV;
vi.restoreAllMocks();
vi.unstubAllGlobals();
});
describe("lookupIpAsn — offline ASN resolver (v1.4.27 B3)", () => {
it("returns null for private + loopback addresses without touching the reader", async () => {
const get = vi.fn();
readerState.asn = get;
readerState.asnExists = true;
const { lookupIpAsn } = await import("../geo");
expect(lookupIpAsn("10.0.0.5")).toBeNull();
expect(lookupIpAsn("127.0.0.1")).toBeNull();
expect(lookupIpAsn("::1")).toBeNull();
expect(lookupIpAsn(null)).toBeNull();
expect(get).not.toHaveBeenCalled();
});
it("returns null when the GeoLite2-ASN MMDB is missing", async () => {
readerState.asnExists = false;
const { lookupIpAsn } = await import("../geo");
expect(lookupIpAsn("8.8.8.8")).toBeNull();
});
it("returns { asn, carrier } when the reader resolves a public IP", async () => {
readerState.asnExists = true;
readerState.asn = () => ({
autonomous_system_number: 3320,
autonomous_system_organization: "Deutsche Telekom AG",
});
const { lookupIpAsn } = await import("../geo");
expect(lookupIpAsn("84.131.0.1")).toEqual({
asn: 3320,
carrier: "Deutsche Telekom AG",
});
});
it("returns null when the reader has no row for the IP", async () => {
readerState.asnExists = true;
readerState.asn = () => null;
const { lookupIpAsn } = await import("../geo");
expect(lookupIpAsn("8.8.8.8")).toBeNull();
});
it("returns the asn with carrier=null when the org field is missing", async () => {
readerState.asnExists = true;
readerState.asn = () => ({ autonomous_system_number: 64500 });
const { lookupIpAsn } = await import("../geo");
expect(lookupIpAsn("8.8.8.8")).toEqual({ asn: 64500, carrier: null });
});
it("swallows reader throws and returns null (caller is fire-and-forget)", async () => {
readerState.asnExists = true;
readerState.asnThrows = true;
const { lookupIpAsn } = await import("../geo");
expect(lookupIpAsn("8.8.8.8")).toBeNull();
});
});
describe("lookupIpLocation — offline-first city resolver (v1.4.27 B3)", () => {
it("prefers the German exonym from the MMDB Names record", async () => {
readerState.cityExists = true;
readerState.city = () => ({
city: { names: { de: "München", en: "Munich" } },
country: { iso_code: "DE" },
});
const fetchSpy = vi.fn();
vi.stubGlobal("fetch", fetchSpy);
const { lookupIpLocation } = await import("../geo");
expect(await lookupIpLocation("85.214.0.1")).toBe("München, DE");
// Offline hit — no online fallback was needed.
expect(fetchSpy).not.toHaveBeenCalled();
});
it("falls back to the English city name when the German exonym is absent", async () => {
readerState.cityExists = true;
readerState.city = () => ({
city: { names: { en: "Birmingham" } },
country: { iso_code: "GB" },
});
const fetchSpy = vi.fn();
vi.stubGlobal("fetch", fetchSpy);
const { lookupIpLocation } = await import("../geo");
expect(await lookupIpLocation("212.58.224.1")).toBe("Birmingham, GB");
});
it("accepts the registered_country ISO when country is absent", async () => {
readerState.cityExists = true;
readerState.city = () => ({
city: { names: { en: "Geneva" } },
registered_country: { iso_code: "CH" },
});
const { lookupIpLocation } = await import("../geo");
expect(await lookupIpLocation("194.158.0.1")).toBe("Geneva, CH");
});
it("falls back to the online provider when the offline DB has no city/country", async () => {
readerState.cityExists = true;
readerState.city = () => ({ city: { names: {} } });
const fetchSpy = vi.fn().mockResolvedValue(
new Response(
new TextEncoder().encode(
JSON.stringify({ success: true, city: "Hamburg", country_code: "DE" }),
).buffer as ArrayBuffer,
{
status: 200,
headers: { "content-type": "application/json; charset=utf-8" },
},
),
);
vi.stubGlobal("fetch", fetchSpy);
const { lookupIpLocation } = await import("../geo");
expect(await lookupIpLocation("8.8.8.8")).toBe("Hamburg, DE");
expect(fetchSpy).toHaveBeenCalledTimes(1);
});
it("falls back to the online provider when the offline DB is missing entirely", async () => {
readerState.cityExists = false;
const fetchSpy = vi.fn().mockResolvedValue(
new Response(
new TextEncoder().encode(
JSON.stringify({ success: true, city: "Berlin", country_code: "DE" }),
).buffer as ArrayBuffer,
{
status: 200,
headers: { "content-type": "application/json; charset=utf-8" },
},
),
);
vi.stubGlobal("fetch", fetchSpy);
const { lookupIpLocation } = await import("../geo");
expect(await lookupIpLocation("8.8.8.8")).toBe("Berlin, DE");
expect(fetchSpy).toHaveBeenCalledTimes(1);
});
it("skips the online fallback when IP_GEO_LOOKUP_DISABLED=1 and offline misses", async () => {
process.env.IP_GEO_LOOKUP_DISABLED = "1";
readerState.cityExists = false;
const fetchSpy = vi.fn();
vi.stubGlobal("fetch", fetchSpy);
const { lookupIpLocation } = await import("../geo");
expect(await lookupIpLocation("8.8.8.8")).toBeNull();
expect(fetchSpy).not.toHaveBeenCalled();
});
});
+183 -18
View File
@@ -1,23 +1,61 @@
/**
* IP geolocation lookup for audit-log enrichment.
*
* Default provider is ipwho.is (HTTPS, free, no key). Both the response
* shape from ipwho.is and the fallback ip-api.com pro endpoint are
* accepted, so swapping providers via IP_GEO_LOOKUP_URL only requires
* matching one of those response shapes.
* v1.4.27 B3: offline-first resolver. The hot path is now a microsecond-
* scale local read against the bundled MaxMind GeoLite2-City MMDB at
* `/opt/geolite2/GeoLite2-City.mmdb` (and the matching GeoLite2-ASN
* database for carrier lookups). The previous `ipwho.is` HTTPS path is
* kept as the second-tier fallback for IPs the offline DB cannot
* resolve (freshly-allocated ranges that lag the monthly GeoLite2
* release roll).
*
* Setting IP_GEO_LOOKUP_DISABLED=1 disables lookup entirely — used by
* deployments that do not want any IP egress to a third-party service
* (V3 audit: GDPR Art. 32 + Art. 44, plaintext HTTP IP egress).
* 1. Private / loopback / opt-out → null (no lookup).
* 2. Offline MMDB hit → return immediately.
* 3. Offline miss → fall back to the existing `ipwho.is` path.
*
* v1.4.16 A8a: the body is decoded as UTF-8 explicitly via
* `TextDecoder('utf-8')` instead of `Response.json()`, and an
* The legacy contract still holds: `lookupIpLocation` returns a
* `"City, CC"` string or `null`, never throws. `lookupIpAsn` is the
* new sibling that resolves the autonomous-system number + the carrier
* organisation string (so the admin login overview can render a
* carrier chip next to the auth provider).
*
* Both helpers are safe to call from any request context. The MMDB
* Reader is loaded lazily on first call and held in a module-level
* cache; the file load is synchronous and not cheap, but it only
* happens once per worker process.
*
* The base path is overridable via `GEOLITE2_DIR` (default
* `/opt/geolite2`). When the DB files are missing the helpers silently
* skip the offline tier — local dev without the MMDBs still works and
* falls straight back to the online provider.
*
* Default provider for the online fallback is ipwho.is (HTTPS, free,
* no key). Both the response shape from ipwho.is and the fallback
* ip-api.com pro endpoint are accepted, so swapping providers via
* `IP_GEO_LOOKUP_URL` only requires matching one of those response
* shapes.
*
* Setting `IP_GEO_LOOKUP_DISABLED=1` disables the online fallback
* entirely — used by deployments that do not want any IP egress to a
* third-party service (V3 audit: GDPR Art. 32 + Art. 44, plaintext
* HTTP IP egress). The offline tier still runs because no egress is
* involved.
*
* v1.4.16 A8a: the online-fallback body is decoded as UTF-8 explicitly
* via `TextDecoder('utf-8')` instead of `Response.json()`, and an
* `Accept-Language: de, en;q=0.5` hint is sent so providers return
* native city names ("Nürnberg") rather than ASCII folds
* ("Nuremberg"). The previous path lost umlauts in production for at
* least one maintainer-flagged login row that rendered as "Nrnberg" in
* /admin/login-overview — see `docs/audit/v1416-summary.md` once cut.
* native city names ("Nürnberg") rather than ASCII folds ("Nuremberg").
* The previous path lost umlauts in production for at least one
* maintainer-flagged login row that rendered as "Nrnberg" in
* /admin/login-overview — see `docs/audit/v1416-summary.md`.
*/
import fs from "node:fs";
import path from "node:path";
import { Reader as MmdbReader } from "mmdb-lib";
import type {
AsnResponse,
CityResponse,
} from "mmdb-lib/lib/reader/response";
interface IpwhoIsResponse {
success?: boolean;
@@ -38,6 +76,98 @@ const PRIVATE_IP =
const DEFAULT_GEO_URL = "https://ipwho.is";
function geoLiteDir(): string {
return process.env.GEOLITE2_DIR ?? "/opt/geolite2";
}
// ── Offline tier (MaxMind GeoLite2) ──────────────────────────────────
//
// Both readers are held in a process-local cache. We use `undefined`
// for "never tried", and `null` for "tried, file missing" so we don't
// pay the `existsSync + readFileSync + parse` cost on every lookup.
interface MmdbCache {
city?: MmdbReader<CityResponse> | null;
asn?: MmdbReader<AsnResponse> | null;
}
const cache: MmdbCache = {};
function loadMmdbReader<T extends import("mmdb-lib/lib/reader/response").Response>(
file: string,
): MmdbReader<T> | null {
try {
const full = path.join(geoLiteDir(), file);
if (!fs.existsSync(full)) return null;
const buf = fs.readFileSync(full);
return new MmdbReader<T>(buf);
} catch {
// Corrupt MMDB or unreadable file → fall back to online tier.
// Never throw from the geo lookup path; the auth-audit caller is
// fire-and-forget and a thrown error would propagate into an
// unhandled rejection.
return null;
}
}
function getCityReader(): MmdbReader<CityResponse> | null {
if (cache.city === undefined) {
cache.city = loadMmdbReader<CityResponse>("GeoLite2-City.mmdb");
}
return cache.city;
}
function getAsnReader(): MmdbReader<AsnResponse> | null {
if (cache.asn === undefined) {
cache.asn = loadMmdbReader<AsnResponse>("GeoLite2-ASN.mmdb");
}
return cache.asn;
}
/**
* Test-only — reset the lazy reader cache so a test can swap the
* `GEOLITE2_DIR` between cases without leaking the previous Reader.
* Not exported from the public surface; the tests import via the
* module-level alias.
*/
export function __resetGeoLite2CacheForTests(): void {
cache.city = undefined;
cache.asn = undefined;
}
/**
* Pick the best-available localised city name from a GeoLite2
* record. German first because the user-base is DACH-skewed; English
* as a graceful fallback for cities that don't have a German exonym.
* The Names map is incomplete in MaxMind for some small German
* towns, so we accept any of the locales the MMDB layout exposes.
*/
function pickCityName(city: CityResponse["city"]): string | null {
if (!city?.names) return null;
return (
city.names.de ??
city.names.en ??
city.names.fr ??
city.names.es ??
null
);
}
function lookupIpLocationOffline(ip: string): string | null {
const reader = getCityReader();
if (!reader) return null;
try {
const row = reader.get(ip);
if (!row) return null;
const city = pickCityName(row.city);
const cc = row.country?.iso_code ?? row.registered_country?.iso_code;
if (!city || !cc) return null;
return `${city}, ${cc}`;
} catch {
return null;
}
}
function buildLookupUrl(ip: string): string {
const base = (process.env.IP_GEO_LOOKUP_URL ?? DEFAULT_GEO_URL).replace(
/\/+$/,
@@ -70,12 +200,8 @@ async function readUtf8Json(res: Response): Promise<unknown> {
return JSON.parse(text);
}
export async function lookupIpLocation(
ip: string | null,
): Promise<string | null> {
if (!ip || PRIVATE_IP.test(ip)) return null;
async function lookupIpLocationOnline(ip: string): Promise<string | null> {
if (process.env.IP_GEO_LOOKUP_DISABLED === "1") return null;
try {
const res = await fetch(buildLookupUrl(ip), {
signal: AbortSignal.timeout(3000),
@@ -109,3 +235,42 @@ export async function lookupIpLocation(
return null;
}
}
export async function lookupIpLocation(
ip: string | null,
): Promise<string | null> {
if (!ip || PRIVATE_IP.test(ip)) return null;
const offline = lookupIpLocationOffline(ip);
if (offline) return offline;
return lookupIpLocationOnline(ip);
}
/**
* Resolve the autonomous-system number + carrier organisation for an
* IP. Offline-only against the bundled GeoLite2-ASN MMDB — the public
* `ipwho.is` endpoint does not expose an ASN field in its free tier,
* so a miss returns `null` rather than falling back to an online
* lookup.
*
* Private / loopback IPs return `null` without touching the reader.
* Same gate the location helper applies.
*/
export function lookupIpAsn(
ip: string | null,
): { asn: number; carrier: string | null } | null {
if (!ip || PRIVATE_IP.test(ip)) return null;
const reader = getAsnReader();
if (!reader) return null;
try {
const row = reader.get(ip);
if (!row) return null;
const asn = row.autonomous_system_number;
if (typeof asn !== "number") return null;
const carrier = row.autonomous_system_organization || null;
return { asn, carrier };
} catch {
return null;
}
}