UID2-7505: Detect unencrypted JSON request bodies in v2 envelope parsing

[swibi-ttd]

Improves the v2 envelope parse error messages. A common integration mistake — sending base64-encoded plain JSON (e.g. via curl) instead of an encrypted request envelope — currently returns the opaque Invalid body: Version mismatch., which gives no hint that the payload must be encrypted.

Changes

1. Detect unencrypted JSON bodies. When envelope parsing fails and the body parses as JSON (an encrypted envelope never does), return a specific error: "Invalid body: The request body is unencrypted JSON. It must be an encrypted request envelope. See <docs> for encryption and decryption code examples." Runs only on the error path.
2. Rename the Version mismatch error, which reads as an operator/API version problem: "Invalid body: Invalid request envelope format version: received X, must be 1." (VERSION constant → ENVELOPE_FORMAT_VERSION.)
3. Append a link-only docs pointer to the other envelope parse errors (not valid base64 / too short / wrong key): "See <docs> for details on the request envelope format." Unlike a cause-asserting hint, this cannot mislead the wrong-secret or proxy-corruption cases.
4. Fix error precedence in the octet-stream → base64 fallback. When both interpretations of an octet-stream body fail, the binary error was always returned — hiding the base64 path's more accurate diagnosis whenever the body was actually base64 text. A binary envelope can never be valid base64 (its first byte is the 0x01 envelope version byte, not a base64 character), so if the fallback got past base64 decoding, the body was base64 text and the fallback's error is returned instead.

Docs links are scope-aware (unifiedid.com / euid.eu); IdentityScope is plumbed from V2PayloadHandler. All existing leading phrases are preserved, and nothing in uid2-operator, uid2-e2e, uid2-validator, or the client SDKs matches the old Version mismatch string.

Testing

New tests for base64-encoded, raw, and short unencrypted JSON bodies, genuine version mismatch, the EUID docs link, and both directions of the octet-stream fallback precedence. mvn clean test: 757 tests, 0 failures.

Jira

UID2-7505

🤖 Generated with Claude Code