decentraland / comms-gatekeeper / 30673716240

85%

main: 85%

Pull #284

github

docs: record why ban status and token retrieval disagree on device bans

A platform ban snapshots the player's device id, and token retrieval matches
it so a banned player reconnecting from the same device under a different
wallet is rejected. GET /users/:address/bans matches on banned_address only,
so it reports that player as not banned. Reading the two side by side, the
endpoint looks like it is missing the device check.

It is not. Document the divergence as intentional so it does not get
"reconciled" later:

- The route is unauthenticated. A device-aware answer would let anyone query
  two arbitrary addresses and infer from a shared ban that both belong to the
  same device, turning it into a wallet-linkage oracle.
- It would hand ban evaders a probe: check a fresh wallet before connecting,
  learn whether the device is already covered, and cycle wallets until one
  comes back clean. Undisclosed means the only way to find the device check is
  to be rejected by it.
- The endpoint receives only an address, so any device it consulted would be
  the last recorded one rather than the device a future connection actually
  arrives from, and could differ from the enforced answer anyway.

Token retrieval remains the sole authority on access; this endpoint answers
the narrower "does this wallet have a ban record?" that a client needs to show
a ban notice.

Documented at the handler, on the two component methods whose contracts differ,
in the OpenAPI description for both operations, and in the architecture notes.
Pinned by an integration test asserting the endpoint reports not banned for a
device-matched wallet while the connection gate rejects it, so closing the gap
fails the build.

Also corrects the ban operation's claim that the device id is "always" banned
alongside the address: it is best-effort and null when the player has never
connected or their client sent no device identifier.

1121 of 1436 branches covered (78.06%)

Branch coverage included in aggregate %.

3081 of 3486 relevant lines covered (88.38%)

75.08 hits per line