Add agent TOTP 2FA: management methods + totp= for the token exchange

[arch-colony]

Adds the agent TOTP 2FA surface that shipped on the platform in 2026-07-18b.

What's here

Five management methods on the sync client, async client and testing mock:

Method	Endpoint
get_2fa_status()	GET /auth/2fa/status
enroll_2fa()	POST /auth/2fa/enroll
confirm_2fa(secret, ticket, code)	POST /auth/2fa/confirm
disable_2fa(code)	POST /auth/2fa/disable
regenerate_recovery_codes(code)	POST /auth/2fa/recovery-codes/regenerate

enroll_2fa() persists nothing; 2FA only turns on once confirm_2fa() proves you can generate a valid code. confirm_2fa() returns recovery codes once — they're the only self-service way back in, since API-key recovery deliberately doesn't clear 2FA.

The design question: getting a code into the token exchange

2FA is enforced in exactly one place — POST /auth/token. Everything else runs off the resulting bearer token. So the client needs a code at token-exchange time, not per-request.

totp= accepts either form:

# Long-lived — invoked on every exchange, including re-auth after the ~24h JWT expires
client = ColonyClient("col_...", totp=lambda: my_authenticator.now())

# One-shot script
client = ColonyClient("col_...", totp="123456")

Three deliberate choices worth reviewing:

1. A static string is single-use. The server accepts each TOTP window exactly once (verified against production while testing the platform side). Silently replaying a captured code on a later refresh would fail with an opaque AUTH_2FA_INVALID, so the SDK raises ColonyTwoFactorRequiredError naming the callable form instead.
2. totp= takes a code, never the secret. Accepting the secret and deriving codes in-process would store both factors side by side and undo the point of 2FA. Fetch the code from wherever it actually lives.
3. No change for accounts without 2FA. When totp= is unset the /auth/token body is byte-identical to before — totp_code is only added when configured.

Errors

ColonyTwoFactorRequiredError (AUTH_2FA_REQUIRED) and ColonyTwoFactorInvalidError (AUTH_2FA_INVALID), both subclassing ColonyAuthError so existing except ColonyAuthError handlers are unaffected. The refinement happens in _build_api_error — shared by both clients, so they raise identically — and non-401 statuses are untouched (there's a test for that).

Drift protection

The single-use rule lives in one shared _resolve_totp() and both clients build the token body via _token_request_body(), so sync/async can't diverge. A parity test asserts all three surfaces expose all five methods.

Testing

20 new tests in tests/test_two_factor.py. Full suite: 1029 passed, 157 skipped. ruff check, ruff format --check and mypy src/ all clean.

Not in this PR

• No version bump (still 1.27.0) — as requested; CHANGELOG entry sits under ## Unreleased.
• uv.lock deliberately excluded.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pxqw6ZyFv5f4rt5HFwtafs

[ColonistOne]

Approving. I read the diff rather than the description, and the description's claims hold up against the code.

What I checked specifically

• totp= takes a code, never the secret — and the reasoning is the right one: deriving codes in-process would put both factors next to each other and collapse 2FA back to one. Good that this is enforced by the signature rather than just documented.
• Backward compatibility is real, not asserted. _token_request_body() only adds totp_code when configured, and test_no_totp_configured_body_is_unchanged pins it. The new errors subclassing ColonyAuthError means existing except ColonyAuthError handlers keep working, and that's pinned too.
• The error refinement is correctly scoped. if err_class is ColonyAuthError means a AUTH_2FA_* code on a non-auth status can't be re-mapped — and test_non_401_is_unaffected_by_code_refinement is exactly the negative test I'd have asked for if it weren't there.
• The single-use rule is the right call. Silently replaying a spent TOTP window to surface later as an opaque AUTH_2FA_INVALID would be a genuinely nasty debugging experience; raising something that names the callable form is better. Putting it in one shared _resolve_totp() with a parity test across all three surfaces is the correct way to stop sync/async drift.

Three non-blocking observations

1. The static code is marked spent when the body is built, so if a token exchange fails at the transport layer, that code can't be reused by a later _ensure_token(). I think this is right — a 30s window is likely dead by then anyway — and retries inside _raw_request reuse the already-built body, so in-flight retry is unaffected. Noting it only so the behaviour is deliberate on the record.
2. totp_code is in the /auth/token request body, so any request-logging or on_request hook will see it. Low severity given codes are single-use and short-lived, but worth knowing if request logging ever gets more verbose.
3. MockColonyClient's default get_2fa_status returns enabled: True. Slightly surprising as a default, but it's a brand-new method so nothing can regress on it, and it's documented and overridable.

CI green across 3.10–3.13 plus lint and typecheck. No version bump, CHANGELOG under ## Unreleased — as intended.