---
type: User Story
title: Enrich portal and game login IPs
description: Login audit events include cached approximate location and network intelligence from ProxyCheck.io.
tags: [security, network, audit, proxycheck]
timestamp: 2026-08-01T22:04:17Z
story_id: US-007
status: verified
---

# User Story

As an operator, I want portal and registered game logins enriched with network context, so that suspicious access can be investigated.

# Acceptance Criteria

- [x] Given a public login IP, then ProxyCheck can provide city, region, country, coordinates, timezone, ASN, provider, risk, and anonymity classification.
- [x] Results are cached in PostgreSQL for 48 hours by default.
- [x] Provider failures are cached briefly and do not deny portal or registered game login.
- [x] Private, loopback, reserved, documentation, and mapped-private addresses are never sent to ProxyCheck.
- [x] Forwarded web IP headers are ignored unless trusted-proxy handling is explicitly enabled.
- [x] Unknown game accounts do not trigger paid ProxyCheck lookups.
- [x] Login events and IP observations retain the available classification and approximate location.
- [x] Users and administrators can see available location and classification in audit views.
- [x] Repeated access observations are summarized by IPv4 /24 or IPv6 /64 network with counts, sources, and latest activity.

# Implementation

- [`packages/network/src/index.ts`](../packages/network/src/index.ts)
- [`apps/web/src/lib/ip-intelligence.ts`](../apps/web/src/lib/ip-intelligence.ts)
- [`apps/web/src/app/auth/discord/route.ts`](../apps/web/src/app/auth/discord/route.ts)
- [`apps/web/src/app/api/velocity/access/route.ts`](../apps/web/src/app/api/velocity/access/route.ts)

# Validation

- [`packages/network/test/proxycheck.test.ts`](../packages/network/test/proxycheck.test.ts)
- [`packages/network/test/client-ip.test.ts`](../packages/network/test/client-ip.test.ts)
- [`packages/network/test/address-groups.test.ts`](../packages/network/test/address-groups.test.ts)
- [`apps/web/src/lib/access-address-groups.test.ts`](../apps/web/src/lib/access-address-groups.test.ts)

# Related Stories

- [Block anonymized additions](us-008-vpn-blocking.md)
- [Preserve an audit trail](us-010-audit-events.md)