Study/server/services/geo.ts
Elijah 85d5c9186d
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m0s
Fifth revision: share-link AI safety, sturdier generation, cleaner UI
- Malformed model JSON is sent back for repair, then retried; a failed job
  starts over once before it fails. Visitors can dismiss failed sets.
- Generated sets get a short distinct name and description; flashcards are
  atomic and have no hints; standard study shows known/learning counts.
- Share links: "In progress" list, finished sets join the normal lists with a
  "New" tag, plain progress steps, newest exam first.
- Share-link AI expires after a week, can be limited to the US or Arizona
  (DB-IP Lite or Cloudflare headers) and is locked by abuse protection
  (migration 8).
- The assistant never answers from general knowledge; MCP and web search
  tools load without a manual test.
- Plain-text copy, no question count in exam mode, filler text removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 09:17:50 -07:00

231 lines
9.9 KiB
TypeScript

/**
* Where a share-link visitor is, for limiting AI features to a region (Settings → Sharing).
*
* Sources, in order: Cloudflare's visitor-location headers when the app trusts its proxy
* (`CF-IPCountry`, and `CF-Region-Code` with the "Add visitor location headers" transform), then
* a local copy of the free DB-IP Lite database (CC BY 4.0, https://db-ip.com), downloaded
* monthly into DATA_DIR/geoip. No visitor address is ever sent anywhere.
*
* Private and loopback addresses count as local and are allowed. A public address that can't
* be placed is refused: the check fails closed.
*/
import fs from 'node:fs';
import net from 'node:net';
import path from 'node:path';
import zlib from 'node:zlib';
import type { Context } from 'hono';
import { Reader } from 'mmdb-lib';
import { z } from 'zod';
import { clientIp } from '../auth.ts';
import type { AppContext } from '../http.ts';
import { getSetting, setSetting } from '../settings.ts';
export const GEO_REGIONS = ['anywhere', 'us', 'arizona'] as const;
export type GeoRegion = (typeof GEO_REGIONS)[number];
const SETTING = 'share.aiRegion';
export const geoRegionSchema = z.object({ region: z.enum(GEO_REGIONS) });
type DbKind = 'country' | 'city';
const MAX_AGE_MS = 32 * 86_400_000;
const RETRY_MS = 6 * 3_600_000;
/** Official monthly files (MaxMind-style records), then the ip-location-db mirror on jsDelivr. */
function sources(kind: DbKind, at = new Date()): { url: string; gzip: boolean }[] {
const month = (d: Date) => `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
const prev = new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth() - 1, 1));
const official = [month(at), month(prev)].map((m) => ({ url: `https://download.db-ip.com/free/dbip-${kind}-lite-${m}.mmdb.gz`, gzip: true }));
const mirror =
kind === 'country'
? [{ url: 'https://cdn.jsdelivr.net/npm/@ip-location-db/dbip-country-mmdb/dbip-country.mmdb', gzip: false }]
: [{ url: 'https://cdn.jsdelivr.net/npm/@ip-location-db/dbip-city-mmdb/dbip-city-ipv4.mmdb', gzip: false }];
return [...official, ...mirror];
}
interface LoadedDb {
reader: Reader<any>;
builtAt: number;
downloadedAt: number;
}
const dbs: Partial<Record<DbKind, LoadedDb>> = {};
const lastError: Partial<Record<DbKind, string>> = {};
const downloading: Partial<Record<DbKind, Promise<void>>> = {};
const lastAttempt: Partial<Record<DbKind, number>> = {};
/** Recent decisions, for the status line in Settings (in memory, last 24 hours). */
const recent: { at: number; outcome: 'allowed' | 'blocked' | 'local' | 'unknown' }[] = [];
export function getGeoRegion(app: AppContext): GeoRegion {
// Tests run without client addresses, so they start unrestricted.
const value = getSetting<string>(app.db, SETTING, app.config.env === 'test' ? 'anywhere' : 'us');
return (GEO_REGIONS as readonly string[]).includes(value) ? (value as GeoRegion) : 'us';
}
export function setGeoRegion(app: AppContext, region: GeoRegion): void {
setSetting(app.db, SETTING, region);
ensureGeoData(app);
}
const dir = (app: AppContext) => path.join(app.config.dataDir, 'geoip');
const file = (app: AppContext, kind: DbKind) => path.join(dir(app), `${kind}.mmdb`);
function loadFromDisk(app: AppContext, kind: DbKind): boolean {
try {
const buf = fs.readFileSync(file(app, kind));
const reader = new Reader<any>(buf);
dbs[kind] = { reader, builtAt: Number(reader.metadata.buildEpoch) || 0, downloadedAt: fs.statSync(file(app, kind)).mtimeMs };
return true;
} catch {
return false;
}
}
async function download(app: AppContext, kind: DbKind): Promise<void> {
lastAttempt[kind] = Date.now();
const errors: string[] = [];
for (const src of sources(kind)) {
try {
const res = await fetch(src.url, { signal: AbortSignal.timeout(kind === 'city' ? 600_000 : 120_000) });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = Buffer.from(await res.arrayBuffer());
const data = src.gzip ? zlib.gunzipSync(body) : body;
new Reader<any>(data); // validates the file before it replaces the old one
fs.mkdirSync(dir(app), { recursive: true });
const tmp = `${file(app, kind)}.tmp`;
fs.writeFileSync(tmp, data);
fs.renameSync(tmp, file(app, kind));
loadFromDisk(app, kind);
delete lastError[kind];
app.log('info', `Location database (${kind}) updated from ${new URL(src.url).host}`);
return;
} catch (err) {
errors.push(`${new URL(src.url).host}: ${err instanceof Error ? err.message : String(err)}`);
}
}
lastError[kind] = `Download failed (${errors.join('; ')})`;
app.log('warn', `Location database (${kind}) could not be downloaded`, lastError[kind]);
}
/** The databases the chosen region needs, loaded from disk and refreshed in the background. */
export function ensureGeoData(app: AppContext): void {
const region = getGeoRegion(app);
if (region === 'anywhere') return;
const needed: DbKind[] = region === 'arizona' ? ['country', 'city'] : ['country'];
for (const kind of needed) {
if (!dbs[kind]) loadFromDisk(app, kind);
const stale = !dbs[kind] || Date.now() - dbs[kind]!.downloadedAt > MAX_AGE_MS;
// Tests never reach the internet.
if (!stale || app.config.env === 'test' || downloading[kind]) continue;
if (lastAttempt[kind] && Date.now() - lastAttempt[kind]! < RETRY_MS) continue;
downloading[kind] = download(app, kind).finally(() => delete downloading[kind]);
}
}
/** Keeps the databases fresh while the server runs. */
export function startGeoSchedule(app: AppContext): () => void {
ensureGeoData(app);
const timer = setInterval(() => ensureGeoData(app), 6 * 3_600_000);
timer.unref();
return () => clearInterval(timer);
}
export function isPrivateAddress(ip: string): boolean {
const v = ip.replace(/^::ffff:/i, '');
if (net.isIPv4(v)) {
const [a, b] = v.split('.').map(Number);
return a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254) || (a === 100 && b >= 64 && b <= 127) || a === 0;
}
if (net.isIPv6(v)) {
const lower = v.toLowerCase();
return lower === '::1' || lower === '::' || lower.startsWith('fc') || lower.startsWith('fd') || lower.startsWith('fe80');
}
return false;
}
export interface GeoCheck {
allowed: boolean;
/** Where the answer came from. */
source: 'off' | 'local' | 'header' | 'database' | 'unknown';
country: string | null;
region: string | null;
ip: string;
}
/** Country and (when known) state from a database record: official DB-IP or the mirror's format. */
function fromRecord(rec: any): { country: string | null; region: string | null } {
if (!rec) return { country: null, region: null };
const country = rec.country?.iso_code ?? rec.country_code ?? null;
const sub = rec.subdivisions?.[0];
const region = sub?.iso_code ? String(sub.iso_code) : (sub?.names?.en ?? rec.state1 ?? null);
return { country: country ? String(country).toUpperCase() : null, region: region ? String(region) : null };
}
const isArizona = (region: string | null) => Boolean(region && /^(az|arizona|us-az)$/i.test(region.trim()));
function record(outcome: (typeof recent)[number]['outcome']): void {
const at = Date.now();
recent.push({ at, outcome });
while (recent.length && (at - recent[0].at > 86_400_000 || recent.length > 5000)) recent.shift();
}
/** Whether this request comes from the region allowed to use AI on share links. */
export function checkVisitorRegion(app: AppContext, c: Context): GeoCheck {
const region = getGeoRegion(app);
const ip = clientIp(c, app.config.trustProxy);
if (region === 'anywhere') return { allowed: true, source: 'off', country: null, region: null, ip };
if (isPrivateAddress(ip)) {
record('local');
return { allowed: true, source: 'local', country: null, region: null, ip };
}
let country: string | null = null;
let state: string | null = null;
let source: GeoCheck['source'] = 'unknown';
if (app.config.trustProxy) {
const cf = c.req.header('cf-ipcountry')?.trim().toUpperCase();
if (cf && /^[A-Z][A-Z0-9]$/.test(cf) && cf !== 'XX') {
country = cf;
state = c.req.header('cf-region-code')?.trim() || null;
source = 'header';
}
}
if (!country || (region === 'arizona' && !state)) {
ensureGeoData(app);
try {
const fromCountry = fromRecord(dbs.country?.reader.get(ip.replace(/^::ffff:/i, '')));
const fromCity = region === 'arizona' ? fromRecord(dbs.city?.reader.get(ip.replace(/^::ffff:/i, ''))) : { country: null, region: null };
if (!country) country = fromCity.country ?? fromCountry.country;
if (!state) state = fromCity.region;
if (country && source === 'unknown') source = 'database';
} catch {
/* an unreadable address: unknown */
}
}
// Anything not placed in the region is refused (Cloudflare marks Tor as T1, which is not US).
const allowed = country === 'US' && (region === 'us' || isArizona(state));
record(country ? (allowed ? 'allowed' : 'blocked') : 'unknown');
return { allowed, source: country ? source : 'unknown', country, region: state, ip };
}
/** For Settings: the chosen region, the databases and what the check has been doing. */
export function geoStatus(app: AppContext) {
const region = getGeoRegion(app);
ensureGeoData(app);
const db = (kind: DbKind) => {
const d = dbs[kind];
return { ready: Boolean(d), builtAt: d?.builtAt ?? null, downloading: Boolean(downloading[kind]), error: d ? null : (lastError[kind] ?? null) };
};
const count = (o: (typeof recent)[number]['outcome']) => recent.filter((r) => r.outcome === o).length;
return {
region,
trustProxy: app.config.trustProxy,
country: db('country'),
city: region === 'arizona' ? db('city') : null,
lastDay: { allowed: count('allowed'), blocked: count('blocked'), local: count('local'), unknown: count('unknown') },
};
}
/** Test hook: forget loaded databases and recent decisions. */
export function resetGeoForTests(): void {
for (const k of Object.keys(dbs) as DbKind[]) delete dbs[k];
recent.length = 0;
}