feat(auth): add Python authentication facade by swkeever · Pull Request #3 · Kong/volcano-sdk-python

swkeever · 2026-08-28T15:01:18Z

Summary

add immutable, redacted auth values and synchronized client session state
implement the full generated-transport-backed authentication facade, including lifecycle, account, OAuth provider, listener, anonymous, password-policy, RFC 8628 device, platform-exchange, and device-session operations
bind the shared VOL-941 authentication acceptance scenarios and document the public API
enforce deterministic quality gates with Ruff ALL, strict Mypy and Pyright, and low complexity and size limits in Pylint

Coordination

Jira: VOL-941
Depends on Kong/volcano-hosting#920 and the resulting generated contract refresh in chore(api): sync OpenAPI contract #2
Uses the shared branch name skeever/vol-941-auth-parity

Verification

repo-wide Ruff lint and format: zero findings
Mypy strict and Pyright strict: zero findings
Pylint complexity, branch, local, return, statement, and try-block limits
126 unit tests
OpenAPI reproducibility check
strict Behave dry-run: 12 scenarios, 63 bound steps
source distribution and wheel build

swkeever · 2026-08-28T15:02:48Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8961e079ca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T16:07:18Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5076d1ddf8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T16:30:58Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2e0416e0c2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T17:01:02Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1b64d8ae7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T17:28:06Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8ba1ceb57a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T17:47:13Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ee8c528528

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T18:06:55Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7cdeda3c75

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T18:23:35Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c1c0aee683

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-08-28T21:01:34Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-28T23:55:47.541748Z	`3a9cbc0`	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2ce360e8f4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T21:28:48Z

@codex review

swkeever · 2026-08-28T21:38:04Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cb49343c2e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T21:46:35Z

@codex review

swkeever · 2026-08-28T21:49:55Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c92c2e6005

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T22:06:36Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f501c6d231

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T22:16:17Z

@codex review

chatgpt-codex-connector · 2026-08-28T22:21:22Z

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: dfaa12ac3e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T22:22:24Z

@codex review

chatgpt-codex-connector · 2026-08-28T22:28:51Z

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 9c743df700

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T23:35:20Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dfb2a2b287

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

swkeever · 2026-08-28T23:47:37Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3a9cbc065e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-08-28T23:55:42Z

+        message = payload.get("message")
+        response_email = payload.get("new_email")
+        if not isinstance(message, str) or not isinstance(response_email, str):
+            raise AuthenticationError(_INVALID_AUTH_RESPONSE)


Accept omitted email-change acknowledgement fields

When auth_request_email_change returns a schema-conforming 200 that omits message or new_email, this check raises AuthenticationError; both properties are optional in openapi/openapi.yaml:5774-5784, and the generated model represents them with UNSET. Use the caller-supplied new_email as the fallback and make the acknowledgement message optional, as with the other acknowledgement endpoints.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-08-28T23:55:42Z

+            response = _mapping(payload)
+            self._client._set_user(_user(_mapping(response.get("user"))))


Reconcile confirmation responses that omit the user

When a successful email-change confirmation omits the optional user property, as permitted by openapi/openapi.yaml:5837-5847, _mapping(None) raises AuthenticationError even though the mutation succeeded. Route this response through the existing user-reconciliation path so an omitted user triggers hydration rather than turning a valid 200 into a failure.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-08-28T23:55:42Z

+            sessions_value = payload.get("sessions", payload.get("data"))
+            if not isinstance(sessions_value, list):
+                raise AuthenticationError(_INVALID_AUTH_RESPONSE)


Treat an omitted session collection as empty

When the session-list endpoint returns {}, this raises AuthenticationError even though the 200 response schema declares both sessions and cursor-mode data optional at openapi/openapi.yaml:6002-6033, and the generated response model accepts that payload. Default an absent collection to an empty list so a schema-conforming empty page produces SessionPage(sessions=()).

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-08-28T23:55:42Z

+def _optional_int(value: object) -> int | None:
+    return value if isinstance(value, int) else None


Exclude booleans from optional integer fields

When a malformed or version-skewed response supplies true for expires_in or a pagination count, isinstance(True, int) succeeds and the SDK exposes True through fields declared as int | None; consumers may consequently interpret an expiry as one second or corrupt pagination calculations. Match _required_int() by checking the exact int type so JSON booleans are not accepted as numeric values.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-08-28T23:55:42Z

+        identity_id=_required_text(payload, "identity_id"),
+        email=_required_text(payload, "email"),


Allow empty identity fields for anonymous methods

When list_methods() includes an active anonymous method, these _required_text() calls reject its identity_id and email because that helper forbids empty strings. The AuthMethodSummary contract explicitly requires both fields while specifying that they are empty for anonymous methods at openapi/openapi.yaml:10562-10569, so listing methods for an anonymous account fails with AuthenticationError; validate presence and type here while allowing empty values for the anonymous method type.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-08-28T23:55:42Z

+            listeners = self._queue_auth_notifications()
+        self.realtime.on_auth_change()


Advance realtime generation atomically with auth state

When an auth change runs on a worker thread, another thread can observe the new current_session after _auth_state_lock is released here but before on_auth_change() advances the realtime generation; an event-loop task in that window passes the old generation checks and can complete a publish through the previous user's socket. Fresh evidence beyond the resolved generation-fencing findings is this state-commit ordering gap: advance the realtime fence while the auth-state commit is still serialized, and apply the same ordering to _clear_auth().

Useful? React with 👍 / 👎.

swkeever · 2026-08-29T00:22:05Z

Superseded by smaller, independently reviewable authentication slices. The branch will remain available as implementation reference.

swkeever added 5 commits August 28, 2026 09:51

feat(auth): add Python authentication state

1b48e8d

feat(auth): expand Python authentication transport

8c706f5

feat(auth): implement Python session lifecycle

36f924e

feat(auth): complete Python authentication facade

b0fb9d6

test(auth): bind Python authentication contract

8961e07

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

chore: enforce strict quality gates

5076d1d

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread docs/authentication.md Outdated

Comment thread pyproject.toml

Comment thread src/volcano_sdk/auth.py

swkeever added 2 commits August 28, 2026 12:22

fix: address authentication review findings

a8968ec

fix: synchronize authentication state

2e0416e

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/client.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/client.py

fix: make authentication state atomic

b1b64d8

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/auth.py

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/auth.py

Comment thread src/volcano_sdk/client.py Outdated

fix: serialize authentication transitions

8ba1ceb

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/_transport.py Outdated

Comment thread src/volcano_sdk/models.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

swkeever added 2 commits August 28, 2026 13:39

fix: distinguish provider authorization failures

d8683b6

fix: preserve authentication invariants

ee8c528

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/realtime.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/client.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

fix: serialize authentication state transitions

7cdeda3

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/realtime.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/models.py Outdated

fix: enforce authentication ownership boundaries

c1c0aee

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/models.py

Comment thread src/volcano_sdk/realtime.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread features/steps/sdk_contract_steps.py

Comment thread src/volcano_sdk/realtime.py

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/realtime.py Outdated

swkeever added 2 commits August 28, 2026 17:24

feat(auth): complete stable authentication surface

7a1847b

fix(realtime): fence publishes across auth changes

844d19e

fix(auth): align device verification contract

cb49343

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/realtime.py Outdated

docs(auth): clarify platform exchange eligibility

118bb00

fix(auth): close concurrency review gaps

c92c2e6

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/realtime.py

Comment thread src/volcano_sdk/client.py Outdated

fix(auth): fence stale asynchronous state

f501c6d

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/realtime.py Outdated

Comment thread src/volcano_sdk/realtime.py

fix(auth): complete realtime cleanup barriers

dfaa12a

fix(realtime): drain completed cleanup snapshots

9c743df

fix(auth): reconcile validated response state

dfb2a2b

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

Comment thread src/volcano_sdk/auth.py Outdated

Comment thread src/volcano_sdk/auth.py Outdated

fix(auth): preserve listener semantics

3a9cbc0

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

swkeever closed this Aug 29, 2026

		response = _mapping(payload)
		self._client._set_user(_user(_mapping(response.get("user"))))

		def _optional_int(value: object) -> int \| None:
		return value if isinstance(value, int) else None

		identity_id=_required_text(payload, "identity_id"),
		email=_required_text(payload, "email"),

		listeners = self._queue_auth_notifications()
		self.realtime.on_auth_change()

Conversation

swkeever commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Coordination

Verification

Uh oh!

swkeever commented Aug 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swkeever commented Aug 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swkeever commented Aug 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swkeever commented Aug 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swkeever commented Aug 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swkeever commented Aug 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

swkeever commented Aug 28, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

swkeever commented Aug 28, 2026 •

edited

Loading

chatgpt-codex-connector Bot commented Aug 28, 2026 •

edited

Loading