44 lines
2.0 KiB
Markdown
44 lines
2.0 KiB
Markdown
---
|
|
type: User Story
|
|
title: Enforce registration at the Velocity proxy
|
|
description: Online-mode Java connections are admitted only after a fail-closed account-manager decision.
|
|
tags: [minecraft, velocity, whitelist, security]
|
|
timestamp: 2026-08-01T18:52:20Z
|
|
story_id: US-009
|
|
status: verified
|
|
---
|
|
|
|
# User Story
|
|
|
|
As a registered player, I want the Velocity proxy to recognize my approved Java account, so that I can join while unknown identities are rejected.
|
|
|
|
# Acceptance Criteria
|
|
|
|
- [x] The plugin sends request ID, server ID, online-mode UUID, username, IP, and occurrence time.
|
|
- [x] Every request uses a high-entropy per-server bearer credential stored only as a hash by the service.
|
|
- [x] Requests outside the 45-second clock window are rejected.
|
|
- [x] Database-unique request IDs reject cross-instance replay attempts.
|
|
- [x] UUID matching is attempted before username fallback.
|
|
- [x] Username fallback applies only when the stored account has no UUID.
|
|
- [x] Successful fallback backfills UUID and canonical username.
|
|
- [x] Changed usernames are persisted and audited.
|
|
- [x] Unknown players, API failures, malformed responses, and unauthorized requests fail closed with registration guidance.
|
|
- [x] The plugin records the real Velocity connection IP and supports Java Edition online mode only.
|
|
|
|
# Implementation
|
|
|
|
- [`plugins/velocity`](../plugins/velocity)
|
|
- [`apps/web/src/app/api/velocity/access/route.ts`](../apps/web/src/app/api/velocity/access/route.ts)
|
|
- [`packages/contracts/src/index.ts`](../packages/contracts/src/index.ts)
|
|
- [`packages/database/src/schema.ts`](../packages/database/src/schema.ts)
|
|
|
|
# Validation
|
|
|
|
- [`plugins/velocity/src/test/java/games/dmg/accountmanager/AccountManagerClientTest.java`](../plugins/velocity/src/test/java/games/dmg/accountmanager/AccountManagerClientTest.java)
|
|
- Shared request and response contracts are covered by [`packages/contracts/test/contracts.test.ts`](../packages/contracts/test/contracts.test.ts).
|
|
|
|
# Related Stories
|
|
|
|
- [Validate Minecraft accounts](us-004-minecraft-validation.md)
|
|
- [Standardize API errors](us-014-problem-details.md)
|