fix: address the security, correctness and design audit (#3)

[sebartyr]

Closes #3.

Reworks authentication, response handling and packaging around every finding in the audit, and adds the test suite and CI the repository was missing.

High-priority findings

1. OAuth implementation is incomplete and replayable — every request is now signed with HMAC-SHA512 over its method, normalized URL, query string and form body, carrying oauth_signature_method, oauth_timestamp, oauth_nonce and oauth_version. The signature base string is validated against the worked example from RFC 5849 §3.4.1.1. SignatureMethod.PLAINTEXT and HMAC_SHA256 remain selectable, PLAINTEXT only as an explicit compatibility mode.

2. Credentials leak through repr() — every credential dataclass redacts its secrets, keeping the non-secret identifiers visible so the repr stays useful. Covered including the nested case (repr({"auth": creds})), which is how structured logging usually leaks them.

3. API path parameters are not encoded — added encode_path_segment(), applied to every identifier. The three reproductions from the audit are regression tests; assertions check url.raw_path (what goes on the wire), since httpx's .path shows the decoded view.

Medium-priority findings

• 4. Empty JSON responses — any successful status may now come without a body; undecodable JSON raises InvalidResponseError; unfollowed 3xx no longer counts as success.
• 5. Fabricated dates — a missing date is None, never now(). All dates normalize to timezone-aware UTC. Required fields are enforced, genuinely optional ones typed | None.
• 6. Lexicographic version ordering — natural ordering, so 10 beats 9; a trailing end-marker keeps 1.0-beta below 1.0.
• 7. Forced JSON Content-Type — only Accept is set globally; httpx derives the rest. A GET now carries no Content-Type, and data={...} is correctly labelled form-encoded.
• 8. OAuth callback and expiration — oauth_callback_confirmed is checked, the callback token is compared against the request token (constant-time), expiration_date is kept and exposed via is_expired(), and mfa_kind is configurable. login() is kept for browser-less automation but documented as not a supported OAuth flow, with the browser flow promoted in the README.
• 9. Deprecated HTTPX TLS APIs — TLS/mTLS go through an ssl.SSLContext; http:// base URLs are refused without an explicit override. Writing the tests surfaced a second deprecated call (per-request cookies= in the dance), also removed; the suite runs clean under -W error::DeprecationWarning.

Additional findings

404 no longer masks a missing application, transport errors are wrapped in TransportError, exception bodies are truncated to 2 KiB, 403 maps to a new AuthorizationError, the instance catalogue is cached per client, idempotent requests retry with backoff/jitter honouring Retry-After (re-signed each attempt, so no nonce reuse), and frozen=True models are now immutable all the way down.

Tests and packaging

217 tests, entirely on httpx.MockTransport — no network access. 95% coverage. Adds py.typed, and CI running ruff, strict mypy and pytest on Python 3.11, 3.12 and 3.13. Verified locally on 3.11 through 3.14.

Breaking changes

Version bumped to 0.2.0; full list in CHANGELOG.md. The main ones: Auth.get_authorization_header() takes the method and URL (a signature is bound to them), strict model parsing raises instead of fabricating values, AuthorizationError is not a subclass of AuthenticationError, list_domains()/get_primary_domain() surface 404, and httpx>=0.28 is required.

Not addressed

Two audit items are left as follow-ups, both API-design calls rather than defects: the batch application-creation redundancy, and the broad use of Any in the NetworkGroups search union, which the API returns as a oneOf the SDK deliberately does not discriminate.