chatgpt-plan-auth 1.0.0__tar.gz

chatgpt_plan_auth-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+# Trusted publishing: no API token anywhere. One-time setup on PyPI:
+#   1. https://pypi.org/manage/account/publishing/ -> "Add a new pending publisher"
+#      PyPI Project Name: chatgpt-plan-auth
+#      Owner: guberm
+#      Repository name: chatgpt-plan-auth
+#      Workflow name: publish.yml
+#      Environment name: (leave empty)
+#   2. Push a tag:  git tag v1.0.0 && git push origin v1.0.0
+# After the first release the publisher is no longer "pending".
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish

chatgpt_plan_auth-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+uv.lock

chatgpt_plan_auth-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Guber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chatgpt_plan_auth-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: chatgpt-plan-auth
+Version: 1.0.0
+Summary: Sign in with ChatGPT (ChatGPT plan usage) for locally hosted apps
+Author-email: Michael Guber <michael@guber.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chatgpt,oauth,openai,pkce,siwc
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: openai>=1.40; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# chatgpt-plan-auth
+
+Sign in with ChatGPT (ChatGPT plan usage) for locally hosted, open-source apps.
+
+Implements the SIWC OAuth flow documented at
+<https://developers.openai.com/siwc/token-sharing-open-source/>: register a
+dynamic client, authorize with PKCE, exchange the code for tokens, keep them
+refreshed and rotated, read the plan's model catalog, and shape Responses API
+requests for the plan usage route. The access token is used as the bearer token
+against `https://api.openai.com/v1` instead of an API key.
+
+The library is a straight extraction of Home Assistant core's
+`openai_conversation/chatgpt_auth.py` (the reviewer's point: deep knowledge of
+an external system belongs in a library, not in core). It carries no Home
+Assistant imports, no `hass`, no config-entry or storage knowledge, and no
+crypto dependency.
+
+```bash
+pip install chatgpt-plan-auth          # protocol only: httpx
+pip install chatgpt-plan-auth[openai]  # + the OpenAI SDK client wrapper
+```
+
+## What lives where
+
+| Module | Contents |
+| --- | --- |
+| `chatgpt_plan_auth.const` | endpoints, `dynamic_agent_client`, scopes, the `ext_agent_host_id` scheme, rejected params/tools lists, model suggestions |
+| `chatgpt_plan_auth.auth` | authorization URL + PKCE/state/nonce, callback parsing, token requests, code exchange, ID token claim validation, credentials, token lifecycle |
+| `chatgpt_plan_auth.catalog` | plan model catalog fetch/parse and the suggestion fallback |
+| `chatgpt_plan_auth.requests` | `shape_request_for_subscription`, `subscription_error_message` |
+| `chatgpt_plan_auth.client` | httpx auth flow and `openai.AsyncOpenAI` subclass (extra: `openai`) |
+
+Everything is caller-driven: no Home Assistant, no global session, no storage.
+
+```python
+import httpx
+from chatgpt_plan_auth import (
+    ChatGPTCredentials, ChatGPTAuth, async_exchange_code, create_authorization_request,
+    create_ext_agent_host_id, parse_callback_url,
+)
+
+host_id = create_ext_agent_host_id()          # generate once, persist it yourself
+request = create_authorization_request(client_id=None, ext_agent_host_id=host_id)
+# send the user to request.url, then read the loopback address bar (any machine):
+params = parse_callback_url(callback_url)
+async with httpx.AsyncClient() as client:
+    credentials = await async_exchange_code(
+        client, params["code"], request=request,
+        callback_client_id=params.get("client_id"), callback_state=params.get("state"),
+    )
+
+# Later, per request:
+auth = ChatGPTAuth(credentials, client=client, on_update=save)  # `save` persists rotation
+token = await auth.async_get_access_token()
+```
+
+Errors: `ChatGPTPlanAuthFatalError` means the stored refresh token can never be
+used again (start your re-authentication flow); any other
+`ChatGPTPlanAuthError` is transient. With the `openai` extra,
+`ChatGPTSubscriptionClient(auth, http_client=...)` attaches the token per
+request and retries once on a 401.
+
+## Deliberate simplification: no ID token signature verification
+
+`/.well-known/jwks.json` is never fetched, RSA keys are never parsed and no JWT
+or crypto dependency is carried — the JWKS helpers and their cache from core are
+gone.
+
+Rationale: the ID token arrives directly from the provider's
+TLS-authenticated token endpoint in the same response as the code exchange. That
+is the trust model Home Assistant's own OAuth2 flow uses, and it is exactly the
+dependency-heavy part the core reviewer objected to. A signature check adds
+nothing there: anyone able to forge the token response could equally forge the
+signature.
+
+What is still verified on every code exchange:
+
+- `iss` is `https://auth.openai.com`
+- `aud` contains the client id the code was exchanged with
+- `exp` is in the future
+- `nonce` equals the nonce of that authorization attempt
+- the callback `state` equals the state of that authorization attempt
+
+Token endpoint errors (`invalid_grant`, `invalid_client`, `token_expired`, ...)
+still surface as fatal errors and never invalidate good credentials.
+
+If you need signature verification — or you cannot trust your network path to
+the token endpoint — verify the ID token against the JWKS in your application
+before calling `validate_id_token`.
+
+## Out of scope (stays in the consuming application)
+
+- Home Assistant: config-entry inspection/storage, `Store` for the host id, the
+  HA http client, config-flow and reauth steps.
+- Application branding: pass `agent_name_hint` (defaults to
+  `chatgpt-plan-auth`).
+- Persisting credentials: the library returns plain mappings
+  (`ChatGPTCredentials.as_entry_data()`), nothing is written to disk.
+
+## Tests
+
+```bash
+uv run --with pytest-asyncio --with openai python -m pytest tests -q
+```
+
+All network access is a fake `httpx.MockTransport`; no test touches the network
+and no test needs key material.

chatgpt_plan_auth-1.0.0/README.md

@@ -0,0 +1,107 @@
+# chatgpt-plan-auth
+
+Sign in with ChatGPT (ChatGPT plan usage) for locally hosted, open-source apps.
+
+Implements the SIWC OAuth flow documented at
+<https://developers.openai.com/siwc/token-sharing-open-source/>: register a
+dynamic client, authorize with PKCE, exchange the code for tokens, keep them
+refreshed and rotated, read the plan's model catalog, and shape Responses API
+requests for the plan usage route. The access token is used as the bearer token
+against `https://api.openai.com/v1` instead of an API key.
+
+The library is a straight extraction of Home Assistant core's
+`openai_conversation/chatgpt_auth.py` (the reviewer's point: deep knowledge of
+an external system belongs in a library, not in core). It carries no Home
+Assistant imports, no `hass`, no config-entry or storage knowledge, and no
+crypto dependency.
+
+```bash
+pip install chatgpt-plan-auth          # protocol only: httpx
+pip install chatgpt-plan-auth[openai]  # + the OpenAI SDK client wrapper
+```
+
+## What lives where
+
+| Module | Contents |
+| --- | --- |
+| `chatgpt_plan_auth.const` | endpoints, `dynamic_agent_client`, scopes, the `ext_agent_host_id` scheme, rejected params/tools lists, model suggestions |
+| `chatgpt_plan_auth.auth` | authorization URL + PKCE/state/nonce, callback parsing, token requests, code exchange, ID token claim validation, credentials, token lifecycle |
+| `chatgpt_plan_auth.catalog` | plan model catalog fetch/parse and the suggestion fallback |
+| `chatgpt_plan_auth.requests` | `shape_request_for_subscription`, `subscription_error_message` |
+| `chatgpt_plan_auth.client` | httpx auth flow and `openai.AsyncOpenAI` subclass (extra: `openai`) |
+
+Everything is caller-driven: no Home Assistant, no global session, no storage.
+
+```python
+import httpx
+from chatgpt_plan_auth import (
+    ChatGPTCredentials, ChatGPTAuth, async_exchange_code, create_authorization_request,
+    create_ext_agent_host_id, parse_callback_url,
+)
+
+host_id = create_ext_agent_host_id()          # generate once, persist it yourself
+request = create_authorization_request(client_id=None, ext_agent_host_id=host_id)
+# send the user to request.url, then read the loopback address bar (any machine):
+params = parse_callback_url(callback_url)
+async with httpx.AsyncClient() as client:
+    credentials = await async_exchange_code(
+        client, params["code"], request=request,
+        callback_client_id=params.get("client_id"), callback_state=params.get("state"),
+    )
+
+# Later, per request:
+auth = ChatGPTAuth(credentials, client=client, on_update=save)  # `save` persists rotation
+token = await auth.async_get_access_token()
+```
+
+Errors: `ChatGPTPlanAuthFatalError` means the stored refresh token can never be
+used again (start your re-authentication flow); any other
+`ChatGPTPlanAuthError` is transient. With the `openai` extra,
+`ChatGPTSubscriptionClient(auth, http_client=...)` attaches the token per
+request and retries once on a 401.
+
+## Deliberate simplification: no ID token signature verification
+
+`/.well-known/jwks.json` is never fetched, RSA keys are never parsed and no JWT
+or crypto dependency is carried — the JWKS helpers and their cache from core are
+gone.
+
+Rationale: the ID token arrives directly from the provider's
+TLS-authenticated token endpoint in the same response as the code exchange. That
+is the trust model Home Assistant's own OAuth2 flow uses, and it is exactly the
+dependency-heavy part the core reviewer objected to. A signature check adds
+nothing there: anyone able to forge the token response could equally forge the
+signature.
+
+What is still verified on every code exchange:
+
+- `iss` is `https://auth.openai.com`
+- `aud` contains the client id the code was exchanged with
+- `exp` is in the future
+- `nonce` equals the nonce of that authorization attempt
+- the callback `state` equals the state of that authorization attempt
+
+Token endpoint errors (`invalid_grant`, `invalid_client`, `token_expired`, ...)
+still surface as fatal errors and never invalidate good credentials.
+
+If you need signature verification — or you cannot trust your network path to
+the token endpoint — verify the ID token against the JWKS in your application
+before calling `validate_id_token`.
+
+## Out of scope (stays in the consuming application)
+
+- Home Assistant: config-entry inspection/storage, `Store` for the host id, the
+  HA http client, config-flow and reauth steps.
+- Application branding: pass `agent_name_hint` (defaults to
+  `chatgpt-plan-auth`).
+- Persisting credentials: the library returns plain mappings
+  (`ChatGPTCredentials.as_entry_data()`), nothing is written to disk.
+
+## Tests
+
+```bash
+uv run --with pytest-asyncio --with openai python -m pytest tests -q
+```
+
+All network access is a fake `httpx.MockTransport`; no test touches the network
+and no test needs key material.

chatgpt_plan_auth-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chatgpt-plan-auth"
+version = "1.0.0"
+description = "Sign in with ChatGPT (ChatGPT plan usage) for locally hosted apps"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Michael Guber", email = "michael@guber.dev" }]
+keywords = ["chatgpt", "oauth", "openai", "pkce", "siwc"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+# The OpenAI SDK wrapper (`chatgpt_plan_auth.client`). The protocol code in
+# `auth`, `catalog` and `requests` never imports it.
+openai = ["openai>=1.40"]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "openai>=1.40"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chatgpt_plan_auth"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["tests"]
+testpaths = ["tests"]

chatgpt_plan_auth-1.0.0/src/chatgpt_plan_auth/__init__.py

@@ -0,0 +1,77 @@
+"""Sign in with ChatGPT (ChatGPT plan usage) for locally hosted apps.
+
+Implements the OAuth flow documented at
+https://developers.openai.com/siwc/token-sharing-open-source/: register a
+dynamic client, authorize with PKCE, exchange the code for tokens, refresh and
+rotate them, read the plan's model catalog, and shape Responses API requests
+for the plan usage route.
+
+The protocol code needs only :mod:`httpx`. The OpenAI SDK wrapper
+(:mod:`chatgpt_plan_auth.client`) needs the ``openai`` extra.
+"""
+
+from .auth import (
+    AuthorizationRequest,
+    ChatGPTCredentials,
+    ChatGPTAuth,
+    async_exchange_code,
+    async_token_request,
+    create_authorization_request,
+    create_ext_agent_host_id,
+    credentials_from_token,
+    parse_callback_url,
+    validate_id_token,
+)
+from .catalog import (
+    async_get_subscription_models,
+    async_get_subscription_models_for_credentials,
+    subscription_model_options,
+)
+from .const import (
+    AUTH_METHOD_CHATGPT,
+    AUTHORIZE_URL,
+    CLIENT_ID_PREFIX,
+    DYNAMIC_AGENT_CLIENT,
+    MODELS_URL,
+    PLAN_SCOPE,
+    REDIRECT_URI,
+    RESOURCE,
+    SCOPE,
+    SUBSCRIPTION_MODEL_SUGGESTIONS,
+    TOKEN_URL,
+)
+from .errors import ChatGPTPlanAuthError, ChatGPTPlanAuthFatalError
+from .requests import shape_request_for_subscription, subscription_error_message
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AUTH_METHOD_CHATGPT",
+    "AUTHORIZE_URL",
+    "CLIENT_ID_PREFIX",
+    "DYNAMIC_AGENT_CLIENT",
+    "MODELS_URL",
+    "PLAN_SCOPE",
+    "REDIRECT_URI",
+    "RESOURCE",
+    "SCOPE",
+    "SUBSCRIPTION_MODEL_SUGGESTIONS",
+    "TOKEN_URL",
+    "AuthorizationRequest",
+    "ChatGPTCredentials",
+    "ChatGPTAuth",
+    "ChatGPTPlanAuthError",
+    "ChatGPTPlanAuthFatalError",
+    "async_exchange_code",
+    "async_get_subscription_models",
+    "async_get_subscription_models_for_credentials",
+    "async_token_request",
+    "create_authorization_request",
+    "create_ext_agent_host_id",
+    "credentials_from_token",
+    "parse_callback_url",
+    "shape_request_for_subscription",
+    "subscription_error_message",
+    "subscription_model_options",
+    "validate_id_token",
+]