PR #36412: refactor(auth): type and bind the change-email token state machine

• Repository: langgenius/dify
• Author: QuantumGhost
• State: open | merged: False
• Link: https://github.com/langgenius/dify/pull/36412

Description (problem / solution / changelog)

AI disclosure: This PR was primarily drafted with Codex using GPT-5.4. I have reviewed and edited the final diff, and I am responsible for the content.

Summary

• keep TokenManager on a shared _TokenData + TypeAdapter baseline, but allow and preserve undeclared extra fields instead of trimming them
• model the change-email token state machine with Pydantic discriminated unions at the AccountService boundary
• bind account_id through the entire change-email flow and validate it at every transition
• expand regression coverage to include shared token-adapter behavior, typed change-email parsing, and account-bound controller transitions

Root cause

PR #35425 introduced the right security model for change-email, but the runtime contract underneath it was still too weak.

The change-email flow depends on a dedicated token state machine:

old_email -> old_email_verified -> new_email -> new_email_verified

However, the shared TokenManager.get_token_data() path was still decoding Redis payloads through a partial _TokenData schema that trimmed undeclared fields. That meant business-specific auth metadata could be silently dropped on readback.

PR #36117 fixed the adjacent generic phase field for forgot-password / email-register, but change-email does not actually use that field at runtime. Change-email needs its own state discriminator plus a stable account_id binding across all transitions.

This PR addresses the problem at the right boundary:

• TokenManager still performs shared baseline validation, but _TokenData now preserves undeclared extra fields instead of stripping them
• change-email converts the raw token dict into typed Pydantic models at the AccountService boundary
• controller transitions now operate on concrete token types and reject tokens whose account_id does not match the logged-in account

Testing

• uv run --project api pytest -o addopts='' api/tests/unit_tests/libs/test_token_manager.py api/tests/unit_tests/controllers/console/test_workspace_account.py -q
• uv run --project api python -m py_compile api/libs/helper.py api/tests/unit_tests/libs/test_token_manager.py api/services/entities/auth_entities.py api/services/account_service.py api/controllers/console/workspace/account.py api/tests/unit_tests/controllers/console/test_workspace_account.py

Fixes #36411

Linear: ENG-426

Changed files

• api/controllers/console/workspace/account.py (modified, +30/-50)
• api/libs/helper.py (modified, +19/-4)
• api/services/account_service.py (modified, +51/-32)
• api/services/entities/auth_entities.py (modified, +139/-1)
• api/tests/unit_tests/controllers/console/test_workspace_account.py (modified, +293/-82)
• api/tests/unit_tests/libs/test_token_manager.py (modified, +123/-43)