81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
# Minecraft Account Manager
|
|
|
|
A Discord-first account registry for a private Java Edition Minecraft network. Players link Discord to one or more Minecraft accounts, while a fail-closed Velocity plugin admits only registered accounts.
|
|
|
|
## Workspace layout
|
|
|
|
- `apps/web` — Next.js 16 web application and API, styled with Tailwind CSS v4
|
|
- `apps/discord-bot` — discord.js slash-command bot
|
|
- `packages/contracts` — shared Zod contracts and CloudEvents types
|
|
- `packages/database` — PostgreSQL Drizzle schema and versioned migrations
|
|
- `plugins/velocity` — fail-closed Velocity admission plugin
|
|
|
|
## Requirements
|
|
|
|
- Node.js 22+
|
|
- npm 11+
|
|
- Docker with Compose, or PostgreSQL 17+
|
|
|
|
## Local setup
|
|
|
|
```bash
|
|
cp .env.example .env.local
|
|
docker compose up -d postgres
|
|
npm install
|
|
npm run db:migrate
|
|
npm run dev
|
|
```
|
|
|
|
Set `DISCORD_GUILD_ID` and `DISCORD_INVITE_URL` in `.env.local` so unauthenticated visitors can reach the Discord server. The HTTPS invite is the most reliable way to open Discord or join; the landing page also offers a `discord://` app link.
|
|
|
|
Set `IP_INTELLIGENCE_PROVIDER=proxycheck`, add `PROXYCHECK_API_KEY`, and configure trusted proxy handling before allowing users to add accounts. Portal and game logins continue if lookup fails, but user account additions fail closed when an address is unknown, VPN, proxy, or Tor.
|
|
|
|
Open `http://localhost:3000`.
|
|
|
|
## Product design
|
|
|
|
Implemented and proposed behavior is tracked as OKF user stories in [`design/index.md`](design/index.md). Validate the bundle with `npm run design:validate`.
|
|
|
|
## Validation
|
|
|
|
```bash
|
|
npm run design:validate
|
|
npm test
|
|
npm run typecheck
|
|
npm run lint
|
|
npm run build
|
|
npm run velocity:build
|
|
```
|
|
|
|
## Database workflow
|
|
|
|
Always create and apply versioned migrations:
|
|
|
|
```bash
|
|
npm run db:generate
|
|
npm run db:migrate
|
|
```
|
|
|
|
Do not use `drizzle push`; it bypasses the reviewed migration history and can cause destructive schema changes.
|
|
|
|
Provision or rotate a Velocity API token after migrating:
|
|
|
|
```bash
|
|
npm run plugin:create-credential --workspace @minecraft-account-manager/database -- velocity-main
|
|
```
|
|
|
|
The token is displayed once and stored only as a SHA-256 hash.
|
|
|
|
## Confirmed product decisions
|
|
|
|
- PostgreSQL and Drizzle ORM
|
|
- Keycloak OIDC for admin access with the `minecraft-account-manager-admin` role
|
|
- Admin user search, account management, primary-account changes, and Discord nickname synchronization
|
|
- Deployment-managed Discord guild ID and invite URL
|
|
- discord.js bot with `/register` and `/account`
|
|
- Java Edition online-mode accounts only
|
|
- Velocity admission checks are fail closed
|
|
- ProxyCheck.io geolocation and VPN/proxy/Tor detection with a 48-hour PostgreSQL cache
|
|
|
|
See [`docs/architecture.md`](docs/architecture.md) for trust boundaries and service responsibilities, [`docs/api-errors.md`](docs/api-errors.md) for the RFC 9457 API error contract, and [`docs/security-review.md`](docs/security-review.md) for implemented controls and production requirements.
|