admin-api — module 0.5

The single control surface for Hermes, the Discord bot and the future web panel — see Architecture › Rules 5 and 6. Phase 0 is read-only. Source in modules/admin-api/.

What it does

A JDK HttpServer on 127.0.0.1:8765 (configurable) answering JSON:

Route	Answer
GET /v1/status	name, version, uptime, player count, module counts, log pipeline counters and sink status, API counters
GET /v1/modules	every module: id, name, version, security class, kernel, dependencies, state
GET /v1/players	online players: uuid, name, latency

curl -H "Authorization: Bearer $SHATTERVEIL_TOKEN" http://127.0.0.1:8765/v1/status

Only GET is served; every other method is 405.

Manifest

Field	Value
id	admin-api
version	0.1.0
security class	CRITICAL — remote access to server state
kernel	yes
dependencies	permissions, logging

Settings

Variable	Meaning
SHATTERVEIL_ADMIN_TOKENS	Comma-separated client:role:secret, e.g. hermes:hermes:<secret>,panel:admin:<secret>. Secrets must be at least 32 characters. No tokens → the module enables but does not listen.
SHATTERVEIL_ADMIN_PORT	Default 8765; 0 picks a free port
SHATTERVEIL_ADMIN_HOST	Default 127.0.0.1; must be a loopback address

Commands

None.

Security

• Binds loopback only; AdminApiConfig refuses any other address.
• Every request needs Authorization: Bearer <secret>. Secrets are compared in constant time against every configured token, and the token's role must hold shatterveil.admin.read in the live PermissionService.
• Per-token rate limit (20 requests/s, burst 40) and a stricter shared limit for requests with no valid token, so guessing is slow.
• Rejected tokens, forbidden roles and rate-limit hits are security AUDIT events with the client name as actor. Successful reads are counted, not logged individually.
• Nothing from the request (headers, query, body) is echoed or logged.

When disabled

Never at runtime (kernel). If the module is disabled (tests only), the port closes and clients get connection refused.

Tests

AdminApiModuleTest: manifest, configuration validation (non-loopback host, weak secrets, duplicate clients, secrets never in toString), the toggle test (port closed), the no-token path, the three routes with 401/403/404/405 handling and audit events on the Minestom test process, and the per-token rate limit.

What's next

Write actions (mute, toggle module, …) with the Hermes approval tiers are Tier 5 work. An OpenAPI specification is planned and will be published here when the API stabilises.