docs(design): add OKF user story catalog

2026-08-01 14:49:37 -04:00
parent 2657399628
commit fa5346458a
21 changed files with 777 additions and 1 deletions
@@ -0,0 +1,41 @@
+---
+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-01T18:43:58Z
+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.
+
+# 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)
+
+# Related Stories
+
+- [Block anonymized additions](us-008-vpn-blocking.md)
+- [Preserve an audit trail](us-010-audit-events.md)