Felis/docs/changes/2026-07-12-felis-nano-hasjoined-resolver.md

Felis-nano — the federating hasJoined multiplexer (step 1: the Go resolver)

• Type: feature (new endpoint) — the verifiable "brain" of Felis-nano
• Date: 2026-07-12
• Area: internal/api (handlers_hasjoined.go + test), internal/api/api.go (route + AuthSources field), docs/openapi.yaml, go.mod
• Task: Felis-nano provides a MultiLogin-like capability — one Velocity proxy that accepts logins verified by several Yggdrasil auth servers at once (Mojang + N third-party roots), 正版优先 (Mojang-first). This change builds step 1: the Go hasJoined multiplexer that does the federating verification. It is the only part of the plan that produces immediate verifiable hard evidence (a unit-tested HTTP endpoint); the two delivery shells that point Velocity at it (a JVM -Dmojang.sessionserver flag, and a thin reflection-hook plugin for third-party servers) are later steps.

What Velocity asks for, and what this answers

On a Minecraft login Velocity's authlib computes the serverId hash and issues GET /session/minecraft/hasJoined?username=<name>&serverId=<hash>[&ip=<ip>] against whatever URL its mojang.sessionserver system property names. A 200 with a game profile means "verified"; a 204 means "not verified" and authlib rejects the login. Vanilla points this at Mojang alone. Felis-nano points it here, and this endpoint fans the same query out to the configured Yggdrasil roots in priority order, returning the first source that validates. Each upstream Yggdrasil runs its own serverId-hash check — the multiplexer only relays, it computes no hashes.

The one non-negotiable transform — per-source UUID namespacing

A third-party Yggdrasil's UUIDs are self-asserted: nothing stops a malicious source from answering with a genuine Mojang player's UUID. If that UUID were emitted as-is, the third-party could impersonate any Mojang player with full UUID fidelity — and the reclaim/ blacklist layer could never catch it, because its whole invariant is "the genuine Mojang player has a different UUID from any squatter." That invariant would simply be false.

So the resolver rewrites every non-identity source's profile into a per-source namespace before it leaves the resolver — the single entry point every login crosses:

canonical = UUIDv3(felisAuthNS, tag + ":" + nativeID)      // third-party
canonical = the source's UUID verbatim                     // Mojang (Identity: true)

MD5 (UUIDv3) preimage resistance means no third-party can mint a value inside Mojang's UUID space; the per-tag prefix means two sources can't collide onto one identity. Every downstream key — account_links, username_blacklist, owner checks — then sees exactly one canonical UUID per real identity, so the reclaim invariant is true by construction, not by assumption.

Fail-closed details that bite if wrong

• Bar gate at the chokepoint. The canonical UUID is checked against Repo.IsUsernameBlacklisted before the profile is returned, so a reclaimed squatter stays out even on a consumer that has no limbo plugin. Keyed on the dashed canonical (.String()) — the exact form Repo.ReclaimUsername stores. A DB error there fails closed (non-200 → authlib rejects), matching the existing handleCheckBlacklist pattern.
• Emit undashed. authlib's GameProfile expects the 32-hex undashed id (hex.EncodeToString(u[:])); the DB/reclaim/blacklist keys are dashed. The resolver checks on the dashed string and emits the undashed one. Mixing the two forms is a silent gate miss — pinned by the tests below.
• properties relayed verbatim ([]json.RawMessage) so a source's signed textures survive the multiplexer untouched.
• Inert by default. AuthSources is nil until cmd/felis wires configured sources, so the endpoint 204s every login until deliberately configured — it ships off.
• Public internal-face route. authlib sends no service token, so the route is mounted Public: true on the internal face (like /healthz); no third face is introduced. The OpenAPI parity test enforces x-felis-face: [internal] + x-felis-tier: public.

Files

File	Change
internal/api/handlers_hasjoined.go	new — handleHasJoined + resolveHasJoined + AuthSource/sessionProfile types + felisAuthNS
internal/api/handlers_hasjoined_test.go	new — TestHasJoined, 7 subtests over httptest fake Yggdrasil roots
internal/api/api.go	AuthSources []AuthSource field (nil = inert) + GET /session/minecraft/hasJoined Public internal route
docs/openapi.yaml	/session/minecraft/hasJoined path — x-felis-face: [internal], x-felis-tier: public, security: []
go.mod	promote github.com/google/uuid indirect→direct (first direct importer)

Verification evidence

Oracle: WSL Fedora-44, go1.26.4. go build ./... → BUILD-OK. Full internal/api package green (ok felis.lolicon.best/internal/api), go vet ./internal/api/ clean. The full package (not a -run filter) was run because this change edits two shared surfaces — the API struct and the internalAPIRoutes() table — where a route that isn't under /api/v1/ is exactly what a route-table-driven invariant test would trip; nothing reddened.

TestHasJoined — 7 subtests, all PASS:

1. mojang identity passthrough — Mojang UUID unchanged, properties relayed.
2. thirdparty UUID rewritten, never emitted as-is — the security invariant: an evil source returns real Notch's Mojang UUID; the resolver emits neither that UUID nor any Mojang-space value, but the deterministic UUIDv3(felisAuthNS, "littleskin:"+id).
3. mojang priority wins over thirdparty — Mojang-first ordering.
4. fallthrough to thirdparty when mojang 204s — priority scan continues past a 204.
5. no source validates -> 204.
6. barred canonical UUID -> 204 — the reused reclaim bar gate holds at the resolver.
7. missing username -> 204 — no source touched on a malformed query.

TestOpenAPIMatchesServedRoutes PASS — the new route's served facets match its docs/openapi.yaml entry in both directions.

Deferred (not in this change)

• Source configuration (step 2): a tag/type/url/priority schema and cmd/felis wiring that populates AuthSources. Until then the endpoint is inert.
• Delivery shells (step 3): Shell 1 = the -Dmojang.sessionserver JVM flag on Felis-managed proxies; Shell 2 = the thin reflection-hook Velocity plugin for third-party servers, plus a Velocity verification runbook. The user has a real server to test Shell 2 against.
• Name-match / textures-signature enforcement — deliberately out of scope: identity is tag:nativeID, not the name, and textures are the cosmetic bucket relayed verbatim.