minecraft-account-manager/design/us-009-velocity-admission.md

type, title, description, tags, timestamp, story_id, status

type	title	description	tags	timestamp	story_id	status
User Story	Enforce registration at the Velocity proxy	Online-mode Java connections are admitted only after a fail-closed account-manager decision.	minecraft velocity whitelist security	2026-08-02T14:12:43Z	US-009	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

• The plugin sends request ID, server ID, online-mode UUID, username, IP, and occurrence time.
• Every request uses a high-entropy per-server bearer credential stored only as a hash by the service.
• Requests outside the 45-second clock window are rejected.
• Database-unique request IDs reject cross-instance replay attempts.
• UUID matching is attempted before username fallback.
• Username fallback applies only when the stored account has no UUID.
• Successful fallback backfills UUID and canonical username.
• Changed usernames are persisted and audited.
• Registered players are allowed only when their single effective group has access enabled; explicit assignments override the default group.
• Disabled group access overrides every schedule; enabled groups with weekly windows admit logins only during an active UTC window.
• Schedule policy is checked before VPN/proxy/Tor policy and is enforced only at login.
• Unknown players, group-disabled players, API failures, malformed responses, and unauthorized requests fail closed with registration guidance.
• The plugin records the real Velocity connection IP and supports Java Edition online mode only.
• After admission, Velocity reports PostLoginEvent as best-effort authenticated telemetry without disconnecting an admitted player when reporting fails.
• Confirmed-connection reports use fresh timestamps and database replay protection.
• Group-disabled and VPN/proxy/Tor-policy denials return distinct operator-configured messages.
• Schedule denials return the configured static template with the effective group, player, and next UTC window.
• The default anonymized-network message directs the player to contact a host for an exception.
• API failures, malformed responses, and unauthorized requests retain fail-closed plugin fallback behavior.

Implementation

• plugins/velocity
• apps/web/src/app/api/velocity/access/route.ts
• apps/web/src/app/api/velocity/connection/route.ts
• packages/contracts/src/index.ts
• packages/database/src/schema.ts

Validation

• plugins/velocity/src/test/java/games/dmg/accountmanager/AccountManagerClientTest.java
• Shared request and response contracts are covered by packages/contracts/test/contracts.test.ts.

Related Stories

• Validate Minecraft accounts
• Standardize API errors
• Control Minecraft admission with groups