Add PawOAuthSession for interactive OAuth sign-in to PAW

[bdunleavy22]

Depends on #1488 (callable access_token, keep_authorization_header). Until that merges, this diff also
shows #1488's commits; only the last four commits are new here.

Open question: does this belong in TM1py.Utils, or would you rather have it in tm1py-samples? It stays out
of RestService and isn't imported by TM1py/__init__.py, so it's easy to move.

Summary

TM1py.Utils.PawOAuth.PawOAuthSession signs a user in to PAW through the browser once (OAuth authorization code
with PKCE), then supplies and refreshes access tokens for TM1Service.

sequenceDiagram
    participant App
    participant PawOAuthSession
    participant Browser
    participant PAW as PAW /oauth2
    participant TM1py
    App->>PawOAuthSession: login()
    PawOAuthSession->>PawOAuthSession: bind 127.0.0.1 listener
    PawOAuthSession->>Browser: open /authorize (PKCE, state)
    Browser-->>PawOAuthSession: redirect with code
    PawOAuthSession->>PAW: exchange code → access + refresh token
    App->>TM1py: TM1Service(access_token=oauth.access_token, keep_authorization_header=True)
    Note over TM1py: on connect / 401 reconnect
    TM1py->>PawOAuthSession: access_token()
    PawOAuthSession->>PAW: refresh if expired

Loading

TM1py/Utils/PawOAuth.py     # PawOAuthSession, TokenCache, InMemoryTokenCache, KeyringTokenCache, OAuthError
Tests/PawOAuth_test.py      # offline: listener, PKCE, token exchange/refresh, keyring cache
docs/getting-started.md     # "Planning Analytics Workspace with OAuth sign-in"
pyproject.toml              # new optional extra: keyring = ["keyring"]

Standard library plus requests; no new required dependencies. cache="keyring" keeps the refresh token in the
OS credential store so later runs refresh silently; the default is cache="in_memory", and any TokenCache can be
passed instead. The keyring entry is keyed on token endpoint host, client ID and scope (never the secret). It needs
the optional keyring package (pip install TM1py[keyring]), which is imported only when that cache is created.

oauth = PawOAuthSession(auth_url=..., token_url=..., client_id=..., redirect_uri=..., cache="keyring")
oauth.login()  # browser the first time, silent refresh afterwards

Evidence

Offline unit tests (Tests/PawOAuth_test.py, 36 tests; keyring is faked, so CI doesn't need it), including:

browser redirects back instantly            -> captured (listener is bound before the browser opens)
idle speculative browser connection         -> redirect still captured within the 5 s read timeout
redirect port already in use                -> OAuthError naming the port
redirect_uri with "localhost"               -> ValueError (loopback IP literals only, RFC 8252 8.3)
forged state / error=access_denied          -> OAuthError
cached refresh token                        -> login() refreshes silently, no browser
expired access token                        -> access_token() refreshes and stores the rotated refresh token
KeyringTokenCache, new process              -> login() refreshes from the stored token, no browser
3500-char refresh token                     -> stored in chunks, read back intact
keyring not installed                       -> ImportError: pip install TM1py[keyring]

KeyringTokenCache against the real Windows Credential Manager backend: without chunking, values over 1280
characters fail with CredWrite: The stub received bad data. With 1000-character chunks, tokens of 100–4000
characters round-trip and are fully removed afterwards.

Against real instances with my own user (manual smoke test, not committed):

	TM1 11.8 on IBM Cloud	TM1 12.5.9 PAaaS
Browser sign-in, refresh token issued	✅	✅
base_url that accepts the token	https://<env>.planning-analytics.cloud.ibm.com/api/v1/tm1/<db>	https://<region>.planninganalytics.saas.ibm.com/api/<tenant>/v0/tm1/<db>
Connect + whoami	✅	✅
Force expiry → re_connect() → new token → whoami	✅	✅
Same with keep_authorization_header=False	401 after session start	401 after session start

Both used scope=v0userContext and a confidential client (secret sent as HTTP Basic). On TM1 11, /tm1/api/<db>
rejects the token (WWW-Authenticate: CAMPassport …): it only accepts CAM, so the docs point to PAW's /api/v1
route instead. With cache="keyring", the first run opened the browser and the second signed in silently.

Merge Danger

Door: two-way for behaviour, but adds public API

Nothing existing imports it, so it can be reverted freely before a release. Once released, renaming or removing
PawOAuthSession would break users, so the name and location are worth settling in review.

Blast Radius: none

New module and a new optional extra only; the module isn't imported by TM1py/__init__.py. Existing connections
and installs are unaffected. Opening a browser and binding a local port happen only when a caller explicitly calls
login().

🤖 Generated with Claude Code