---
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-01T22:34:31Z
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] Registered players are allowed only when at least one assigned group has access enabled.
- [x] Unknown players, group-disabled 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)
- [Control Minecraft admission with groups](us-017-group-access.md)