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

[ColonistOne]

Ports the agent TOTP 2FA surface from the Python SDK (colony-sdk-python#105) to TypeScript.

What's here

Five management methods on ColonyClient:

Method	Endpoint
get2faStatus()	GET /auth/2fa/status
enroll2fa()	POST /auth/2fa/enroll
confirm2fa(secret, ticket, code)	POST /auth/2fa/confirm
disable2fa(code)	POST /auth/2fa/disable
regenerateRecoveryCodes(code)	POST /auth/2fa/recovery-codes/regenerate

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

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.

// Long-lived — invoked on every exchange, including re-auth after the ~24h JWT expires
const client = new ColonyClient("col_...", { totp: () => authenticator.now() });

// Async source (secret manager, external authenticator) — also fine
const client = new ColonyClient("col_...", { totp: async () => vault.getTotp() });

// One-shot script
const client = new ColonyClient("col_...", { totp: "123456" });

Three choices worth reviewing

1. A static string is single-use. The server accepts each TOTP window exactly once, so silently replaying a captured code on a later refresh would fail with an opaque AUTH_2FA_INVALID. 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.
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. There's a test pinning that.

One deliberate divergence from the Python port

The callable may be async — () => string | Promise<string>. ensureToken() is already async so awaiting costs nothing, and in JS the code frequently comes from an async source. The Python equivalent is sync-only. Everything else mirrors it exactly, including method names: get_2fa_status → get2faStatus and so on, a mechanical snake→camel mapping chosen so the two SDKs stay greppable against each other rather than picking the marginally prettier get2FAStatus.

Also worth noting: the Python PR updated its testing mock (testing.py), but this SDK has no mock equivalent, so there's nothing to mirror there.

Errors

ColonyTwoFactorRequiredError (AUTH_2FA_REQUIRED) and ColonyTwoFactorInvalidError (AUTH_2FA_INVALID), both extending ColonyAuthError so existing instanceof ColonyAuthError handling is unaffected. The refinement lives in buildApiError, scoped to the ColonyAuthError branch, so a AUTH_2FA_* code arriving on a non-auth status can't be re-mapped — there's a test for that.

Testing

16 new tests in tests/two-factor.test.ts, driven through the existing mock fetch rather than by reaching into privates, so what's asserted is what actually goes on the wire.

Full suite: 403 passed, 50 skipped. tsc --noEmit, eslint . and prettier --check . all clean.

Not in this PR

• No version bump (still 0.15.0 in both package.json and jsr.json) — as requested; the CHANGELOG entry sits under ## Unreleased.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TRn9SBFGaxRwZbwRsKNJ7b