feat: interactive OIDC device-flow authentication (questdb.auth)

[glasstiger]

Summary

New questdb.auth module that lets you sign in interactively to OIDC-secured
QuestDB Enterprise from Python — including from remote kernels (JupyterHub,
SageMaker, Colab, VS Code-remote, containers) that have no local browser.

It runs the OAuth 2.0 Device Authorization Grant (RFC 8628)
entirely client-side: you authorize in any browser (laptop or phone), while the
kernel only makes outbound calls to your identity provider (IdP). The resulting
token is presented to QuestDB over the auth paths it already supports — HTTP
Authorization: Bearer or PG-wire _sso — so no server change is required.

Pure Python, built on the standard library (urllib); questdb.ingress is
never imported at module load, and all optional deps are lazy.

Two ways to use it

Just the token — no extra dependencies; works with PG-wire, HTTP, or any client:

from questdb.auth import OidcDeviceAuth

auth = OidcDeviceAuth.from_questdb("https://questdb.example.com:9000")
token = auth.token()        # device flow on first use, else cached / refreshed
headers = auth.headers()    # {"Authorization": "Bearer <token>"}

The integrated session — query to a DataFrame and feed adapters:

from questdb.auth import connect

qdb = connect("https://questdb.example.com:9000")   # interactive sign-in
df = qdb.sql("SELECT * FROM trades LIMIT 10")        # REST /exec -> pandas
engine = qdb.sqlalchemy_engine()                     # PG-wire, token as _sso
with qdb.sender() as sender:                         # ingestion (ILP over HTTP)
    ...

On first use you get a sign-in prompt (clickable link in Jupyter, plain text on
a terminal). Re-running is silent: the token is cached and refreshed silently as
it nears expiry.

Highlights

• Config auto-discovery from the QuestDB /settings endpoint (acl.oidc.*),
  falling back to the IdP .well-known/openid-configuration. Anything passed
  explicitly overrides discovery; discovery can also be skipped entirely.
• Correct token selection mirroring QuestDB's own logic
  (groupsEncodedInToken ? id_token : access_token), requesting the openid
  scope automatically when the id_token is sent. A completed grant that is
  missing the required token kind fails once with a clear error rather than
  caching an unusable token.
• Token lifecycle: in-process cache with silent refresh via the
  refresh_token; re-prompts only when the refresh token is missing/rejected,
  while a transient network error is surfaced (not re-prompted). A lock
  serializes refresh so parallel cells/threads don't double-prompt. Cache
  backends: "memory" (default — process-global, survives notebook cell
  re-runs), None (no cache, prompt every time), or a custom TokenCache
  instance. Tokens are never written to disk.
• Connection adapters: pandas (REST /exec), SQLAlchemy, psycopg/psycopg2,
  and the ingestion Sender.
• Non-interactive detection: raises OidcInteractionRequired instead of
  hanging under papermill / cron / CI.
• Jupyter-first prompt (clickable link, optional QR code via qrcode) with a
  plain-text terminal fallback.
• Typed errors: every failure path raises an OidcError subclass
  (OidcConfigError, OidcNetworkError, OidcInteractionRequired,
  OidcDeviceFlowError, OidcTimeoutError, OidcAuthError) — malformed config,
  HTTP/URL errors and bad server payloads are mapped to these rather than leaking
  raw ValueError / AttributeError / http.client exceptions.

Security

• No IdP passwords are entered in the notebook; MFA/SSO happen at the IdP.
• https is required; plaintext is allowed only to a loopback address.
  insecure=True permits plaintext to a non-loopback QuestDB host only — it
  never downgrades the IdP (so the device code and refresh token are never
  sent in cleartext) and never disables certificate verification.
• The credential (device-authorization / token) endpoints must share one
  origin, and HTTP redirects are refused — urllib doesn't strip the
  Authorization header across a cross-origin 30x, and the origin check only
  sees the pre-redirect URL, so a silently-followed redirect could leak the token
  or refresh token. A 30x on those endpoints surfaces as an error instead.
• Out-of-band IdP pin — pass issuer= / discovery_url= to pin the IdP. The
  discovery origin is never derived from a server-supplied token endpoint, so a
  tampered /settings can't redirect the device-code / refresh-token POSTs. The
  pin is required before trusting credential endpoints that arrive over an
  untrusted plaintext /settings (only reachable with insecure=True).
• Only server-authoritative /settings config is trusted — discovery reads
  the nested config object and ignores the user-writable preferences sibling
  (which the web console persists via PUT /settings), so a user who can write a
  preference can't smuggle an acl.oidc.* override (e.g. a redirected token
  endpoint) into the resolved config.
• Hardened device-flow poll — the IdP-supplied expires_in / interval are
  clamped (sane lifetime cap, interval in [1s, 60s], never sleeps past the
  deadline), so a hostile or buggy IdP can't time the flow out before the first
  poll or stall the loop while it holds the acquisition lock.
• Terminal output is sanitized — C0/C1 control characters (incl. ESC) are
  stripped from untrusted device-response fields (verification_uri,
  user_code, IdP error_description, JWT-derived identity) before they reach
  the TTY, so a MITM'd response can't inject ANSI escapes to spoof the prompt.
  The Jupyter renderer already HTML-escapes its output.
• Credentials kept out of logs — TokenSet is immutable (frozen) and keeps
  the access/id/refresh tokens out of its repr, so a token can't leak into a
  log line or traceback. Adapters avoid logging the token / PG DSN.
• Honours HTTPS_PROXY, REQUESTS_CA_BUNDLE, SSL_CERT_FILE, and ca_bundle=.

Dependencies & Python support

token() / headers() need nothing beyond the standard library. pandas,
sqlalchemy, psycopg / psycopg2, qrcode and IPython are imported
lazily, only when used. Minimum supported Python is raised to 3.10.

Docs, examples & tests

• New guide docs/auth.rst (:ref:oidc_auth), API reference in docs/api.rst
  (incl. TokenCache, TokenSet, MemoryCache, NullCache), index/installation
  updates, and a CHANGELOG.rst entry.
• Runnable example examples/oidc_device_auth.py.
• test/test_auth.py — pure-Python (no compiled extension required), wired into
  the suite via test/test.py. Covers the device flow, refresh, non-interactive
  contexts, discovery, REST/PG adapters, concurrency, endpoint validation,
  cache-key derivation, and transport/renderer security.

Also in this PR (CI & build robustness)

Bundled fixes to keep the matrix green, independent of the auth feature:

• pandas 3 / numpy 2: derive the expected dtype in test_parquet_roundtrip
  instead of hardcoding object (pandas 3 reads back the new string dtype); keep
  32-bit wheel targets on the consistent pandas 2 / numpy 1 stack so the
  dataframe tests actually run there.
• QuestDB-master leg on JDK 25: build/run questdb master on JDK 25, build its
  -SNAPSHOT java client via the local-client Maven profile (new
  ci/templates/detect-local-client.yml), invoke Maven directly (the Maven task
  can't parse JDK 25), and pass the JPMS module-access flags the server needs.
• Windows: silence mock-server tracebacks on abrupt client disconnect
  (ConnectionError family), and skip the readonly AZP_ENHANCED* agent var in
  the wheel-build env re-export.
• Updates the internal review-pr review skill (.claude/skills/review-pr/).

Summary by CodeRabbit

• New Features

  • Added interactive OIDC device-authorization authentication with token caching and automatic refresh (including a file-backed option).
  • Introduced a high-level authentication/session helper with REST SQL execution, SQLAlchemy/PG connectivity, ingestion support, and Jupyter/terminal sign-in prompts, plus a new device-auth example.

• Documentation

  • Added OIDC authentication guide, expanded auth API reference, and updated docs navigation and dependency/installation notes.

• Compatibility

  • Raised minimum supported Python version to 3.10.

• Tests

  • Added comprehensive authentication/discovery/adapter/concurrency/security tests; improved CI/test robustness.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR introduces the questdb.auth package implementing client-side OAuth 2.0 Device Authorization Grant (RFC 8628) OIDC authentication for QuestDB Enterprise. The package includes a stdlib HTTP client, token cache backends, OIDC endpoint discovery, device-flow rendering for terminal and Jupyter, the core OidcDeviceAuth token manager, a QuestDB session with REST/SQLAlchemy/psycopg/ILP adapters, a full unit test suite, and comprehensive documentation. The minimum Python version is raised to 3.10. An unrelated Claude PR review skill document is also added.

Changes

questdb.auth OIDC Device Authorization Grant

Layer / File(s)	Summary
Exception hierarchy and Python version bump src/questdb/auth/_errors.py, setup.py, docs/installation.rst	Defines OidcError and seven typed subclasses; raises python_requires to >=3.10 in setup.py and updates the installation docs accordingly.
Stdlib HTTP client with TLS and security enforcement src/questdb/auth/_http.py	Implements build_ssl_context, HttpResponse, loopback detection, HTTPS-only enforcement for non-loopback hosts, request(), get_json(), and post_form() using only Python stdlib.
TokenSet and cache backends src/questdb/auth/_cache.py	Defines TokenSet with clock-skew-aware validity, TokenCache interface, and three implementations: MemoryCache (thread-safe), NullCache, and FileCache (atomic JSON writes, cross-process fcntl/msvcrt locking) plus make_cache() factory.
OIDC configuration discovery and endpoint validation src/questdb/auth/_discovery.py	Implements OidcConfig, QuestDB /settings fetching/flattening, IdP .well-known fallback, relative endpoint resolution, same-origin and issuer-pin validation, and resolve_config() orchestrator.
Device-flow prompt rendering src/questdb/auth/_render.py	Adds scheme-safe link validation, TerminalRenderer (plain-text + ASCII QR), JupyterRenderer (updatable HTML display + base64 PNG QR), environment detection, and make_renderer() factory.
OidcDeviceAuth token manager src/questdb/auth/_device.py	Implements OidcDeviceAuth with from_questdb() classmethod, token lifecycle (cache gate → silent refresh → RFC 8628 device flow with poll loop), _tokenset_from_response, secure IdP transport, URL normalization, and browser-open safety.
QuestDB session and connection adapters src/questdb/auth/_questdb.py	Adds QuestDB wrapper with sql() (REST /exec → pandas DataFrame), sqlalchemy_engine() (per-connection token injection), psycopg() (_sso auth), sender() (ILP bearer), and top-level connect().
Public API, example, changelog, and docs src/questdb/auth/__init__.py, examples/oidc_device_auth.py, docs/auth.rst, docs/api.rst, docs/index.rst, CHANGELOG.rst	Wires __all__ for the public surface; adds a runnable example; adds comprehensive Sphinx documentation covering usage modes, discovery, caching, adapters, IdP requirements, and security; registers the auth toctree entry and updates the changelog.
Unit test suite, test infrastructure, and CI compatibility test/test_auth.py, test/test.py, test/test_dataframe.py, test/mock_server.py, ci/pip_install_deps.py, ci/cibuildwheel.yaml	Adds 1167 lines covering device flow, non-interactive, refresh, file cache, discovery, REST adapter, concurrency, adapter mocks, config helpers, endpoint validation, cache-key normalization, transport security, and renderer security; registers all test classes; updates pandas dtype compatibility and pandas 3/32-bit wheel checks; makes HTTP test server quiet on abrupt connection closures; extends Windows env-var filtering.

Claude PR Review Skill

Layer / File(s)	Summary
review-pr SKILL.md .claude/skills/review-pr/SKILL.md	Defines a 4-step PR review workflow with 10 parallel agents, review level controls, change-surface mapping, verification requirements, comprehensive checklists (correctness, Cython/C-ABI, GIL, performance, tests), and structured output format for findings.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant connect as questdb.auth.connect()
  participant OidcDeviceAuth
  participant resolve_config
  participant QuestDB_Settings as QuestDB /settings
  participant IdP
  participant Renderer
  participant TokenCache
  participant QuestDB_Session as QuestDB session

  User->>connect: connect(url, eager=True)
  connect->>OidcDeviceAuth: from_questdb(url)
  OidcDeviceAuth->>resolve_config: url, overrides
  resolve_config->>QuestDB_Settings: GET /settings
  QuestDB_Settings-->>resolve_config: acl.oidc.* config
  resolve_config->>IdP: GET /.well-known/openid-configuration (if needed)
  IdP-->>resolve_config: device_authorization_endpoint
  resolve_config-->>OidcDeviceAuth: OidcConfig
  connect->>QuestDB_Session: QuestDB(url, auth)
  connect->>OidcDeviceAuth: token() [eager]
  OidcDeviceAuth->>TokenCache: load(cache_key)
  TokenCache-->>OidcDeviceAuth: miss
  OidcDeviceAuth->>IdP: POST device_authorization_endpoint
  IdP-->>OidcDeviceAuth: device_code, user_code
  OidcDeviceAuth->>Renderer: on_prompt(resp)
  Renderer-->>User: display verification URI + user code
  loop Poll IdP
    OidcDeviceAuth->>IdP: POST token_endpoint (device_code grant)
    IdP-->>OidcDeviceAuth: authorization_pending / tokens
  end
  OidcDeviceAuth->>TokenCache: store(cache_key, TokenSet)
  OidcDeviceAuth->>Renderer: on_success(identity, expires_in)
  connect-->>User: QuestDB session
  User->>QuestDB_Session: sql("SELECT ...") / sender() / sqlalchemy_engine()

Loading

🎯 4 (Complex) | ⏱️ ~75 minutes

🐇 Hoppity-hop through device flows and grants,
A token appears after suitable chants!
The IdP polls, the cache stores with care,
A Bearer in headers floats freshly through air.
Jupyter glows, the terminal prints neat—
OIDC for QuestDB, the login's complete! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately captures the primary change: introduction of interactive OIDC device-flow authentication. It is concise, specific, and directly reflects the main feature addition across the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ia_oidc_device_flow

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 6

🧹 Nitpick comments (1)

src/questdb/auth/_questdb.py (1)

82-94: 💤 Low value

Chain the import exception for better diagnostics.

When both psycopg and psycopg2 fail to import, the raised ImportError loses the underlying cause. Chaining the exception preserves the diagnostic context.

Suggested fix

 def _pg_module():
     try:
         import psycopg  # type: ignore  # psycopg v3
         return psycopg
     except ImportError:
         pass
     try:
         import psycopg2  # type: ignore
         return psycopg2
-    except ImportError:
+    except ImportError as e:
         raise ImportError(
             'A PostgreSQL driver is required: install `psycopg` (v3) or '
-            '`psycopg2-binary`.')
+            '`psycopg2-binary`.') from e

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/questdb/auth/_questdb.py` around lines 82 - 94, The second except
ImportError block in the _pg_module() function should preserve the exception
chain for better diagnostics. Capture the ImportError exception in the second
except block using `as e` syntax, then use `raise ... from e` syntax when
raising the new ImportError to chain the exception, which preserves the
underlying cause and provides better debugging context.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/skills/review-pr/SKILL.md:
- Around line 157-162: The Step 3 preamble at lines 157-162 states that every
agent receives the full change-surface map, but Agent 10's input contract at
lines 231-240 explicitly limits it to only the PR diff and changed file names.
Add an explicit exception clause in the Step 3 preamble section to clarify that
Agent 10 does not receive the full change-surface map and instead receives only
the diff and changed file names, ensuring consistency between the general rule
and the specific Agent 10 behavior documented at lines 231-240.
- Around line 39-42: The table at lines 39-42 states that level 0 (default)
skips Step 2.5, but there is a later reference (around lines 144-155) that marks
Step 2.5e as mandatory at every level, creating a contradiction. Fix this
inconsistency by clarifying the level 0 description in the table: either modify
the "Skip Step 2.5" statement to specify that Step 2.5e is an exception and is
still performed, or restructure it to list exactly which substeps (2.5a, 2.5b,
2.5c, 2.5d, 2.5e) are executed or skipped. Ensure the description at level 0 and
the mandatory requirement stated at lines 144-155 are aligned so the default
path is no longer self-contradictory.

In `@docs/auth.rst`:
- Around line 65-76: The code example in the documentation is missing the import
statement for TimestampNanos, which is used in the sender.row() method call. Add
an import statement at the top of the code snippet to include TimestampNanos
from the questdb.ingress module (or appropriate module) so that the example can
be executed successfully when copied verbatim.

In `@src/questdb/auth/__init__.py`:
- Around line 75-92: The `__all__` list in the module needs to be sorted
alphabetically to comply with Ruff's RUF022 rule and maintain consistency in the
public API exports. Reorder all the items in the `__all__` list (which includes
'connect', 'QuestDB', 'OidcDeviceAuth', 'OidcConfig', 'TokenCache', 'TokenSet',
'MemoryCache', 'FileCache', 'NullCache', and the various OidcError types) in
alphabetical order while ensuring all items remain in the list.

In `@src/questdb/auth/_http.py`:
- Around line 123-129: The `_opener()` function doesn't receive the `insecure`
parameter, so it cannot enforce HTTPS-only redirect policies. To fix this, add
an `insecure` parameter to the `_opener()` function signature. When
`insecure=False`, create a custom redirect handler that validates redirects do
not downgrade from HTTPS to HTTP for non-loopback hosts (similar to the
validation in `_require_secure()`), and pass this handler to
`urllib.request.build_opener()` instead of using the default. When
`insecure=True`, use urllib's default redirect handling. Update all callers of
`_opener()` to pass the `insecure` parameter value.

In `@test/test_auth.py`:
- Around line 600-605: The timed joins with a 10-second timeout do not verify
that threads actually completed, which can cause non-daemon threads to remain
running and hang the test process if a regression causes a deadlock. After
calling t.join(10) on each thread in both the loop at lines 600-605 and at lines
828-835, add a verification check that confirms each thread has terminated by
asserting that t.is_alive() returns False, or raise an exception if any thread
is still alive after the timeout. This ensures the test fails cleanly rather
than leaving hanging threads.

---

Nitpick comments:
In `@src/questdb/auth/_questdb.py`:
- Around line 82-94: The second except ImportError block in the _pg_module()
function should preserve the exception chain for better diagnostics. Capture the
ImportError exception in the second except block using `as e` syntax, then use
`raise ... from e` syntax when raising the new ImportError to chain the
exception, which preserves the underlying cause and provides better debugging
context.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bf4af383-9022-4ae5-b189-73691f4ccd00

📥 Commits

Reviewing files that changed from the base of the PR and between a523b3a and 4559587.

📒 Files selected for processing (18)

• .claude/skills/review-pr/SKILL.md
• CHANGELOG.rst
• docs/api.rst
• docs/auth.rst
• docs/index.rst
• docs/installation.rst
• examples/oidc_device_auth.py
• setup.py
• src/questdb/auth/__init__.py
• src/questdb/auth/_cache.py
• src/questdb/auth/_device.py
• src/questdb/auth/_discovery.py
• src/questdb/auth/_errors.py
• src/questdb/auth/_http.py
• src/questdb/auth/_questdb.py
• src/questdb/auth/_render.py
• test/test.py
• test/test_auth.py