HealthLog/docs/audit/v1427-summary.md

v1.4.27 release summary

Overview

v1.4.27 polishes the settings shell rhythm and lands the offline-first geolocation pipeline that drives the /admin/login-overview table. Two MaxMind GeoLite2 databases (GeoLite2-City + GeoLite2-ASN) are now bundled into the runtime image; the resolver in src/lib/geo.ts reads them with mmdb-lib and falls back to the existing ipwho.is HTTPS path only when the local DB cannot resolve the address.

GeoLite2 attribution

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com. The GeoLite2 databases (GeoLite2-City and GeoLite2-ASN) are distributed under the Creative Commons Attribution-ShareAlike 4.0 International License.

The same attribution renders on the /about page so an end user can discover it without inspecting the repository.

Operating the offline databases

The MMDB files are too large to vendor in git. They are downloaded outside the Docker build by scripts/fetch-geolite2.sh. The operator runs the script before docker build with a free MaxMind license key:

MAXMIND_LICENSE_KEY=xxxx ./scripts/fetch-geolite2.sh

The script writes GeoLite2-City.mmdb and GeoLite2-ASN.mmdb to assets/geolite2/. The Dockerfile then copies the folder into /opt/geolite2/ so the runtime resolver finds the databases on disk. If the script is skipped the image builds cleanly, and the resolver falls back to the online ipwho.is provider — the v1.4.26 behaviour.

The offline tier is optional as of v1.4.27 R5. When MAXMIND_LICENSE_KEY is unset the Fetch GeoLite2 databases step in .github/workflows/docker-publish.yml emits a ::warning::, drops an .empty marker into assets/geolite2/, and continues — the build no longer blocks on a missing secret. The runtime resolver detects the marker on the first public-IP lookup, sends a one-shot admin notification with the GitHub Actions secrets URL, and continues to serve audits from the ipwho.is fallback. /api/version exposes offlineGeoEnabled: boolean so the admin status page can render the state at a glance.

MaxMind reissues the databases on the first Tuesday of each month; re-run the script before each release to pick up new ASN allocations and city renames.

Schema delta

AuditLog grows two nullable columns:

• asn Int? — the autonomous-system number resolved from the GeoLite2-ASN DB at audit-creation time.
• carrier String? — the matching autonomous_system_organization string (e.g. "Deutsche Telekom AG").

Both columns are additive and IF NOT EXISTS-guarded so the migration is idempotent on the demo server which may already carry hand-edited columns from a prior partial run.

Backfill helper

src/lib/jobs/geo-backfill.ts walks rows where location IS NULL and createdAt > now() - 30 days, capped at 5 000 rows per pass, and re-resolves them through the offline DB. Useful after a fresh GeoLite2 DB roll so the historical rows that landed during an ipwho.is outage finally pick up a city + carrier label.

Image-size budget

The two MMDB files add ~80 MB to the production image. The tzdata-bearing Alpine runner stage already sits at ~330 MB compressed; the v1.4.27 image lands well under the 90 MB image-size delta budget set out in the fix plan.

Convention-compliance exemptions

The release-wide convention forbids the substrings AI, Claude, agent, marathon, wave, phase, session, subagent, and Anthropic in user-facing artifacts. Two exemptions remain by necessity and are recorded here so future audits can stop re-opening the same finding:

• Vendor-name dropdown options. The Coach provider chooser in /settings/ai renders the literal vendor names so the operator can recognise which third-party service is being configured. The keys settings.ai.providerOptions.anthropic and settings.ai.activeProviderOptions.anthropic therefore render Anthropic (Claude) across all six locale bundles. Rebranding these would break the recognition the dropdown exists to provide. The exemption applies to any vendor label whose product is the setting being chosen, e.g. OpenAI, Anthropic, Codex.
• GitHub repository URL on /about. The source-link on the public about page renders https://github.com/MBombeck/HealthLog. The username segment is an irreducible technical identifier for the URL and cannot be hidden without breaking the link. The directive's spirit — never surface the maintainer's full name in prose — is honoured: the /about page never spells "Marc" or "Bombeck" in body copy, only inside the URL.