@yahyahammad/venastine 0.3.8 → 0.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,747 +1,747 @@
1
- """The ChatGPT plan's credential: signing in, staying signed in, signing out
2
- (ROADMAP_v3 §83 slice 1; CG4-CG6, CG9, CG10, CG12).
3
-
4
- OpenAI's Sign in with ChatGPT lets a Plus or Pro subscriber spend their plan
5
- inside an open-source app that runs locally, which is the test HD5 set for
6
- any sign-in: the provider's own documentation invites the third-party app
7
- in. A remotely hosted app needs OpenAI's interest form first, so nothing
8
- here runs on a hosted deployment (CG1); the TUI refuses before it gets here.
9
-
10
- WHAT IS HERE AND WHAT IS NOT. Everything about the credential that is not
11
- drawing: the registration OpenAI makes during the first sign-in, the
12
- one-shot listener its redirect comes back to, the code exchange, the ID
13
- token check, the token file, refreshing it, and revoking it. The TUI owns
14
- the asking and the words; `core/connect.py` owns the preset; slice 2's
15
- Responses path in `core/client.py` is the only caller of `access_token()`,
16
- which the openai SDK calls before every request (CG21).
17
-
18
- WHAT SLICE 0 MEASURED THAT THIS RELIES ON, on the owner's account
19
- (batches 181-183): the callback carries `client_id`, `code`, `scope` and
20
- `state`; access and ID tokens last 3600 s; the ID token is RS256 with a
21
- `kid`; `earliest_refresh_at` is epoch seconds about six minutes before
22
- expiry and is advice rather than a floor; a refresh rotates the refresh
23
- token; revocation answers an empty 200 and kills the access token at once.
24
-
25
- THE TOKEN FILE (CG4) is `chatgpt_auth.json` beside `providers.json`, 0600
26
- and written atomically, and every read-modify-write of it happens under one
27
- lock held across threads AND processes, because a refresh token rotates:
28
- two harness processes refreshing at once would each spend the same one. The
29
- lock is the operating system's (`fcntl.flock`, `msvcrt.locking`) on an
30
- empty sidecar file, so a process that dies holding it releases it.
31
-
32
- NOTHING HERE LOGS A TOKEN, A CODE OR A VERIFIER. Errors carry an HTTP status
33
- and OpenAI's error code, never a body.
34
-
35
- NO HTTP LIBRARY IS IMPORTED AT MODULE SCOPE, for `core/connect.py`'s reason:
36
- every network call goes through a `post` or `get` callable the caller may
37
- replace, and the defaults are that module's.
38
- """
39
-
40
- from __future__ import annotations
41
-
42
- import base64
43
- import hashlib
44
- import hmac
45
- import http.server
46
- import logging
47
- import os
48
- import secrets
49
- import threading
50
- import time
51
- import uuid
52
- from collections.abc import Callable
53
- from contextlib import contextmanager
54
- from dataclasses import dataclass, field
55
- from typing import Optional
56
- from urllib.parse import parse_qsl, urlencode, urlsplit
57
-
58
- import credentials
59
- from core import connect
60
- from json_store import read_versioned, write_json_atomic
61
-
62
- logger = logging.getLogger(__name__)
63
-
64
- ISSUER = "https://auth.openai.com"
65
- RESOURCE = "https://api.openai.com/v1"
66
- SCOPE = ("openid profile email offline_access resource.invoke "
67
- "chatgpt.tokens.use.direct")
68
- PLAN_SCOPE = "chatgpt.tokens.use.direct"
69
- DYNAMIC_CLIENT = "dynamic_agent_client"
70
- # What OpenAI shows on its consent page and in ChatGPT's connected apps: the
71
- # app's own title, as its page asks (CG6).
72
- AGENT_NAME = "Venastine Research Harness"
73
- CALLBACK_PATH = "/auth/callback"
74
- # Read by the owner from ChatGPT on 2026-10-26 (slice 0); no API reports it.
75
- USAGE_URL = "https://chatgpt.com/settings/usage?tab=overview"
76
- # CG1 in one sentence, wherever a hosted deployment meets the plan:
77
- # /connect, /model, /critic and the launch warning (batch 195). It moved
78
- # here from tui/app.py so credentials.py can say it too.
79
- LOCAL_ONLY = (
80
- "The ChatGPT plan signs in on a local install only: OpenAI offers it to "
81
- "open-source apps running on your own machine, and its sign-in comes "
82
- "back to 127.0.0.1, which a hosted deployment is not.")
83
-
84
- AUTH_FILE = "chatgpt_auth.json"
85
- STORE_VERSION = 1
86
- # How long a sign-in waits for the browser to come back (CG5).
87
- SIGN_IN_WAIT_S = 600
88
- # Refresh this long before expiry at the latest, whatever
89
- # `earliest_refresh_at` says.
90
- REFRESH_MARGIN_S = 300
91
- # How long to wait for another process's hold on the token file.
92
- LOCK_WAIT_S = 30
93
- # Pauses before each revocation attempt: the first is immediate.
94
- REVOKE_PAUSES_S = (0, 2, 5)
95
-
96
- # OpenAI's codes for a refresh token that will never work again. Anything
97
- # else -- a network failure, a 5xx, a code not on this list -- keeps every
98
- # stored token (CG10).
99
- UNUSABLE_REFRESH = frozenset({
100
- "invalid_grant", "invalid_refresh_token", "token_expired",
101
- "refresh_token_expired", "refresh_token_invalidated",
102
- "refresh_token_reused",
103
- })
104
-
105
- Post = Callable[[str, dict], tuple[int, dict]]
106
- Get = Callable[[str], tuple[int, dict]]
107
-
108
-
109
- class ChatGPTAuthError(connect.ConnectError):
110
- """A sign-in step that cannot go on. The message is safe to show."""
111
-
112
-
113
- class SignedOut(ChatGPTAuthError):
114
- """There is no usable sign-in: never made, signed out, or ended by OpenAI."""
115
-
116
-
117
- class Transient(ChatGPTAuthError):
118
- """A refresh failed for a reason that may pass; every token was kept."""
119
-
120
-
121
- # ---------------------------------------------------------------------------
122
- # ---- The token file and its lock --------------------------------------------
123
- # ---------------------------------------------------------------------------
124
-
125
- def auth_path() -> str:
126
- """`chatgpt_auth.json` beside `providers.json`, wherever that is.
127
-
128
- Read through the module at call time, as `credentials` itself is, so a
129
- test's monkeypatch of `credentials.LLM_PROVIDERS_FILE` and a user's
130
- AGENT_PROVIDERS_FILE both move this file with it (#24).
131
- """
132
- return os.path.join(os.path.dirname(credentials.LLM_PROVIDERS_FILE),
133
- AUTH_FILE)
134
-
135
-
136
- def _read() -> dict:
137
- data = read_versioned(auth_path(), STORE_VERSION,
138
- "treating the ChatGPT plan as signed out.")
139
- return data or {"version": STORE_VERSION}
140
-
141
-
142
- def _write(data: dict) -> None:
143
- # 0600 at creation, for credentials._write_secret_json's reason: these
144
- # are bearer tokens for a paid plan.
145
- data["version"] = STORE_VERSION
146
- write_json_atomic(auth_path(), data, mode=0o600, indent=2)
147
-
148
-
149
- if os.name == "nt":
150
- import msvcrt
151
-
152
- def _try_lock(fd: int) -> bool:
153
- os.lseek(fd, 0, os.SEEK_SET)
154
- try:
155
- msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
156
- except OSError:
157
- return False
158
- return True
159
-
160
- def _unlock(fd: int) -> None:
161
- os.lseek(fd, 0, os.SEEK_SET)
162
- msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
163
- else:
164
- import fcntl
165
-
166
- def _try_lock(fd: int) -> bool:
167
- try:
168
- fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
169
- except OSError:
170
- return False
171
- return True
172
-
173
- def _unlock(fd: int) -> None:
174
- fcntl.flock(fd, fcntl.LOCK_UN)
175
-
176
-
177
- _THREAD_LOCK = threading.RLock()
178
- _HELD = threading.local()
179
-
180
-
181
- @contextmanager
182
- def _locked():
183
- """Hold the token file against every other thread and process (CG4).
184
-
185
- Re-entrant within a thread: an OS lock taken twice by one process on two
186
- descriptors deadlocks on POSIX, so a nested `with` only counts.
187
- """
188
- with _THREAD_LOCK:
189
- depth = getattr(_HELD, "depth", 0)
190
- if depth:
191
- _HELD.depth = depth + 1
192
- try:
193
- yield
194
- finally:
195
- _HELD.depth = depth
196
- return
197
- path = auth_path() + ".lock"
198
- parent = os.path.dirname(path)
199
- if parent:
200
- os.makedirs(parent, exist_ok=True)
201
- fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o600)
202
- try:
203
- deadline = time.monotonic() + LOCK_WAIT_S
204
- while not _try_lock(fd):
205
- if time.monotonic() >= deadline:
206
- raise Transient(
207
- "Another Venastine process is holding the ChatGPT "
208
- "plan's token file; try again in a moment.")
209
- time.sleep(0.05)
210
- _HELD.depth = 1
211
- try:
212
- yield
213
- finally:
214
- _HELD.depth = 0
215
- _unlock(fd)
216
- finally:
217
- os.close(fd)
218
-
219
-
220
- # ---------------------------------------------------------------------------
221
- # ---- Discovery ----------------------------------------------------------------
222
- # ---------------------------------------------------------------------------
223
-
224
- def discover(get: Optional[Get] = None) -> dict:
225
- """The four endpoints, from OpenAI's discovery document, checked.
226
-
227
- The issuer must be OpenAI's and every endpoint https on its host: a
228
- document naming somewhere else is refused rather than followed. The
229
- hosted bridge's `deploy/hosted/sign_in.discover` makes the same checks
230
- for ModelScope; it is not imported because `deploy/` is not shipped to
231
- npm.
232
- """
233
- get = get or connect.get_json
234
- status, doc = get(f"{ISSUER}/.well-known/openid-configuration")
235
- if status != 200:
236
- raise ChatGPTAuthError(
237
- f"OpenAI's sign-in configuration answered HTTP {status}.")
238
- if doc.get("issuer") != ISSUER:
239
- raise ChatGPTAuthError(
240
- "OpenAI's sign-in configuration names another issuer; nothing "
241
- "was connected.")
242
- host = urlsplit(ISSUER).hostname
243
- endpoints = {}
244
- for name in ("authorization_endpoint", "token_endpoint",
245
- "revocation_endpoint", "jwks_uri"):
246
- url = doc.get(name) or ""
247
- parts = urlsplit(url)
248
- if parts.scheme != "https" or parts.hostname != host:
249
- raise ChatGPTAuthError(
250
- f"OpenAI's sign-in configuration gives no usable {name}; "
251
- f"nothing was connected.")
252
- endpoints[name] = url
253
- return endpoints
254
-
255
-
256
- # ---------------------------------------------------------------------------
257
- # ---- Signing in ---------------------------------------------------------------
258
- # ---------------------------------------------------------------------------
259
-
260
- class _Listener:
261
- """The one-shot server OpenAI's redirect comes back to (CG5).
262
-
263
- 127.0.0.1 on a free port, `/auth/callback` only, and only an answer
264
- whose `state` matches: anything else is told no and changes nothing.
265
- The first matching answer wins. The request line is never logged,
266
- because it is where the authorization code arrives.
267
- """
268
-
269
- def __init__(self, state: str):
270
- self.state = state
271
- self.params: Optional[dict] = None
272
- self.answered = threading.Event()
273
- listener = self
274
-
275
- class Handler(http.server.BaseHTTPRequestHandler):
276
- def log_message(self, *args):
277
- pass
278
-
279
- def do_GET(self):
280
- parts = urlsplit(self.path)
281
- if parts.path != CALLBACK_PATH:
282
- self._reply(404, "Not here.")
283
- return
284
- params = dict(parse_qsl(parts.query))
285
- if not hmac.compare_digest(params.get("state", ""),
286
- listener.state):
287
- self._reply(400, "This answer belongs to another "
288
- "sign-in.")
289
- return
290
- if listener.answered.is_set():
291
- self._reply(400, "This sign-in was already answered.")
292
- return
293
- listener.params = params
294
- listener.answered.set()
295
- self._reply(200, "Done. You can close this tab and go back "
296
- "to Venastine.")
297
-
298
- def _reply(self, code: int, text: str) -> None:
299
- body = text.encode("utf-8")
300
- self.send_response(code)
301
- self.send_header("Content-Type", "text/plain; charset=utf-8")
302
- self.send_header("Content-Length", str(len(body)))
303
- self.end_headers()
304
- self.wfile.write(body)
305
-
306
- self._server = http.server.HTTPServer(("127.0.0.1", 0), Handler)
307
- self.port = self._server.server_address[1]
308
- self._closed = False
309
- threading.Thread(target=self._server.serve_forever,
310
- name="chatgpt-sign-in", daemon=True).start()
311
-
312
- def close(self) -> None:
313
- if self._closed:
314
- return
315
- self._closed = True
316
- self._server.shutdown()
317
- self._server.server_close()
318
-
319
-
320
- @dataclass
321
- class SignIn:
322
- """One sign-in in progress. `close()` it whichever way it ends."""
323
-
324
- url: str
325
- redirect_uri: str
326
- state: str = field(repr=False)
327
- nonce: str = field(repr=False)
328
- verifier: str = field(repr=False)
329
- endpoints: dict = field(repr=False)
330
- listener: _Listener = field(repr=False)
331
-
332
- def wait(self, timeout: float) -> Optional[dict]:
333
- """The callback's parameters, or None if none came in time."""
334
- if self.listener.answered.wait(timeout):
335
- return self.listener.params
336
- return None
337
-
338
- def close(self) -> None:
339
- self.listener.close()
340
-
341
-
342
- def _b64url(raw: bytes) -> str:
343
- return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
344
-
345
-
346
- def start(*, get: Optional[Get] = None) -> SignIn:
347
- """Begin a sign-in: the URL to open, and the listener waiting for it.
348
-
349
- The host id is made once per install and kept (CG6). A saved
350
- registration's client id is sent when there is one; otherwise
351
- `dynamic_agent_client` and the app's name, which is how OpenAI
352
- registers the app during the first sign-in (CG12).
353
- """
354
- endpoints = discover(get)
355
- with _locked():
356
- data = _read()
357
- if not data.get("host_id"):
358
- data["host_id"] = f"urn:uuid:{uuid.uuid4()}"
359
- _write(data)
360
- host_id = data["host_id"]
361
- saved = (data.get("registration") or {}).get("client_id")
362
-
363
- verifier = _b64url(secrets.token_bytes(64))
364
- challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
365
- state = secrets.token_urlsafe(32)
366
- nonce = secrets.token_urlsafe(32)
367
- listener = _Listener(state)
368
- redirect_uri = f"http://127.0.0.1:{listener.port}{CALLBACK_PATH}"
369
- query = {"client_id": saved or DYNAMIC_CLIENT}
370
- if not saved:
371
- query["agent_name_hint"] = AGENT_NAME
372
- query.update({
373
- "ext_agent_host_id": host_id,
374
- "response_type": "code",
375
- "redirect_uri": redirect_uri,
376
- "scope": SCOPE,
377
- "resource": RESOURCE,
378
- "state": state,
379
- "nonce": nonce,
380
- "code_challenge": challenge,
381
- "code_challenge_method": "S256",
382
- })
383
- url = f"{endpoints['authorization_endpoint']}?{urlencode(query)}"
384
- return SignIn(url, redirect_uri, state, nonce, verifier, endpoints,
385
- listener)
386
-
387
-
388
- def pasted_params(sign_in: SignIn, text: str) -> dict:
389
- """The callback's parameters from an address the person pasted (CG5).
390
-
391
- For a browser on another machine, which cannot reach this listener: the
392
- address it ended on is the same redirect, checked the same way --
393
- exactly this sign-in's host, port and path, and its `state`.
394
- """
395
- parts = urlsplit((text or "").strip())
396
- expected = urlsplit(sign_in.redirect_uri)
397
- if (parts.scheme, parts.hostname, parts.port, parts.path) != (
398
- expected.scheme, expected.hostname, expected.port, expected.path):
399
- raise ChatGPTAuthError(
400
- f"That is not the address this sign-in ends on; it starts with "
401
- f"{sign_in.redirect_uri}?")
402
- params = dict(parse_qsl(parts.query))
403
- if not hmac.compare_digest(params.get("state", ""), sign_in.state):
404
- raise ChatGPTAuthError(
405
- "That address belongs to another sign-in. /connect chatgpt "
406
- "starts a fresh one.")
407
- return params
408
-
409
-
410
- @dataclass(frozen=True)
411
- class Completed:
412
- """How a sign-in ended. `notice_due` is CG8's one-time notice."""
413
-
414
- plan_usage: bool
415
- notice_due: bool
416
-
417
-
418
- def verify_id_token(token: str, client_id: str, nonce: str, jwks_uri: str,
419
- *, get: Optional[Get] = None) -> dict:
420
- """The ID token's claims, once it is shown to be OpenAI's (CG6).
421
-
422
- RS256 and nothing else -- the algorithm is pinned before a key is
423
- chosen, so a token claiming `none` or an HMAC is refused rather than
424
- checked against a public key used as a secret. Then the signature
425
- against the published keys, the issuer, the audience (this install's
426
- client id), expiry, and the nonce this sign-in sent.
427
- """
428
- import jwt
429
-
430
- get = get or connect.get_json
431
- if not token:
432
- raise ChatGPTAuthError("OpenAI sent no ID token; nothing was "
433
- "connected.")
434
- try:
435
- header = jwt.get_unverified_header(token)
436
- except jwt.PyJWTError:
437
- raise ChatGPTAuthError("OpenAI's ID token is unreadable; nothing was "
438
- "connected.") from None
439
- if header.get("alg") != "RS256":
440
- raise ChatGPTAuthError(
441
- f"OpenAI's ID token is signed with {header.get('alg')!r}, not "
442
- f"RS256; nothing was connected.")
443
- status, jwks = get(jwks_uri)
444
- if status != 200:
445
- raise ChatGPTAuthError(
446
- f"OpenAI's signing keys answered HTTP {status}; nothing was "
447
- f"connected.")
448
- try:
449
- keys = jwt.PyJWKSet.from_dict(jwks).keys
450
- except jwt.PyJWTError:
451
- raise ChatGPTAuthError("OpenAI's signing keys are unreadable; nothing "
452
- "was connected.") from None
453
- kid = header.get("kid")
454
- matching = [k for k in keys if k.key_id == kid] if kid else list(keys)
455
- if not matching:
456
- raise ChatGPTAuthError("No published OpenAI key matches the ID token; "
457
- "nothing was connected.")
458
- try:
459
- claims = jwt.decode(
460
- token, matching[0].key, algorithms=["RS256"], audience=client_id,
461
- issuer=ISSUER, leeway=60,
462
- options={"require": ["exp", "iat", "iss", "aud", "sub"]})
463
- except jwt.PyJWTError as exc:
464
- raise ChatGPTAuthError(
465
- f"OpenAI's ID token did not verify ({type(exc).__name__}); "
466
- f"nothing was connected.") from None
467
- if not hmac.compare_digest(str(claims.get("nonce", "")), nonce):
468
- raise ChatGPTAuthError("OpenAI's ID token answers another sign-in; "
469
- "nothing was connected.")
470
- return claims
471
-
472
-
473
- def _session_from(body: dict, granted: list, now: float) -> dict:
474
- earliest = body.get("earliest_refresh_at")
475
- return {
476
- "access_token": body["access_token"],
477
- "refresh_token": body["refresh_token"],
478
- "expires_at": now + int(body.get("expires_in") or 3600),
479
- "earliest_refresh_at": (float(earliest)
480
- if isinstance(earliest, (int, float))
481
- else None),
482
- "scopes": granted,
483
- "plan_usage": PLAN_SCOPE in granted,
484
- }
485
-
486
-
487
- def complete(sign_in: SignIn, params: dict, *, post: Optional[Post] = None,
488
- get: Optional[Get] = None,
489
- now: Callable[[], float] = time.time) -> Completed:
490
- """Trade the callback's code for tokens, check them, and store them.
491
-
492
- ONE ACCOUNT PER INSTALL (CG12): a saved registration's client id is
493
- what the exchange uses, and a callback naming a different one -- a
494
- different ChatGPT account -- is refused, as OpenAI's page says to.
495
- `/disconnect chatgpt --forget` is how the install changes account.
496
-
497
- A sign-in that did not grant the plan scope is still kept, with
498
- `plan_usage` false, and said so (CG6). A previous session's refresh
499
- token is revoked once the new one is stored, so a second sign-in does
500
- not leave a first one alive at OpenAI.
501
- """
502
- post = post or connect.post_form
503
- if not hmac.compare_digest(params.get("state", ""), sign_in.state):
504
- raise ChatGPTAuthError("That answer belongs to another sign-in.")
505
- if params.get("error"):
506
- if params["error"] == "access_denied":
507
- raise ChatGPTAuthError("The sign-in was declined at OpenAI; "
508
- "nothing was connected.")
509
- raise ChatGPTAuthError(f"OpenAI ended the sign-in "
510
- f"({params['error']}); nothing was connected.")
511
- code = params.get("code")
512
- if not code:
513
- raise ChatGPTAuthError("OpenAI's answer carried no code; nothing was "
514
- "connected.")
515
- issued = params.get("client_id") or ""
516
- with _locked():
517
- saved = (_read().get("registration") or {}).get("client_id")
518
- if saved and issued and issued != saved:
519
- raise ChatGPTAuthError(
520
- "That sign-in was for a different ChatGPT account than this "
521
- "install is registered to. /disconnect chatgpt --forget, then "
522
- "/connect chatgpt, switches accounts.")
523
- client_id = saved or issued
524
- if not client_id:
525
- raise ChatGPTAuthError("OpenAI's answer carried no client id; nothing "
526
- "was connected.")
527
-
528
- status, body = post(sign_in.endpoints["token_endpoint"], {
529
- "grant_type": "authorization_code",
530
- "client_id": client_id,
531
- "code": code,
532
- "code_verifier": sign_in.verifier,
533
- "redirect_uri": sign_in.redirect_uri,
534
- "resource": RESOURCE,
535
- })
536
- if (status != 200 or not body.get("access_token")
537
- or not body.get("refresh_token")):
538
- why = body.get("error") or f"HTTP {status}"
539
- raise ChatGPTAuthError(
540
- f"OpenAI did not accept the sign-in ({why}). /connect chatgpt "
541
- f"starts a fresh one.")
542
- claims = verify_id_token(body.get("id_token"), client_id, sign_in.nonce,
543
- sign_in.endpoints["jwks_uri"], get=get)
544
- granted = sorted(str(body.get("scope") or params.get("scope") or "")
545
- .split())
546
- session = _session_from(body, granted, now())
547
- account = claims["sub"]
548
-
549
- with _locked():
550
- data = _read()
551
- registration = data.get("registration") or {}
552
- shown = (bool(registration.get("notice_shown"))
553
- and registration.get("account") == account)
554
- previous = data.get("session") or {}
555
- data["registration"] = {"client_id": client_id, "account": account,
556
- "notice_shown": shown}
557
- data["endpoints"] = dict(sign_in.endpoints)
558
- data["session"] = session
559
- _write(data)
560
- logger.info("chatgpt: signed in; plan usage %s", session["plan_usage"])
561
-
562
- old = previous.get("refresh_token")
563
- if old and old != session["refresh_token"]:
564
- _revoke(sign_in.endpoints["revocation_endpoint"], client_id, old,
565
- post, time.sleep, pauses=(0,))
566
- return Completed(plan_usage=session["plan_usage"],
567
- notice_due=session["plan_usage"] and not shown)
568
-
569
-
570
- def mark_notice_shown() -> None:
571
- """Record that CG8's one-time notice was shown to this account."""
572
- with _locked():
573
- data = _read()
574
- registration = data.get("registration")
575
- if registration:
576
- registration["notice_shown"] = True
577
- _write(data)
578
-
579
-
580
- # ---------------------------------------------------------------------------
581
- # ---- Staying signed in --------------------------------------------------------
582
- # ---------------------------------------------------------------------------
583
-
584
- def access_token(*, post: Optional[Post] = None,
585
- now: Callable[[], float] = time.time,
586
- replacing: Optional[str] = None) -> str:
587
- """A current access token, refreshed first when it is due (CG4, CG10).
588
-
589
- Due at `earliest_refresh_at`, or `REFRESH_MARGIN_S` before expiry,
590
- whichever comes first. The refresh happens under the lock, on a file
591
- read AFTER the lock was taken -- another process may already have
592
- refreshed, and its replacement is then the token to use -- and the
593
- replacement is written before it is returned, because the refresh token
594
- it replaced is spent.
595
-
596
- `replacing` is the token a request was just refused with, a 401
597
- (batch 188): it makes the refresh due whatever the clock says, but only
598
- while the file still holds that token. When it does not, another thread
599
- or process has already replaced it, and the replacement is returned
600
- without spending a second refresh.
601
-
602
- A refresh OpenAI refuses as unusable clears the session and raises
603
- `SignedOut`. Anything else -- a network failure, a 5xx, a code not on
604
- `UNUSABLE_REFRESH` -- raises `Transient` and keeps every token.
605
- """
606
- post = post or connect.post_form
607
- with _locked():
608
- data = _read()
609
- session = data.get("session")
610
- if not session:
611
- raise SignedOut("The ChatGPT plan is not signed in. /connect "
612
- "chatgpt signs in.")
613
- moment = now()
614
- earliest = session.get("earliest_refresh_at")
615
- due = (moment >= session["expires_at"] - REFRESH_MARGIN_S
616
- or (earliest is not None and moment >= earliest)
617
- or (replacing is not None
618
- and session["access_token"] == replacing))
619
- if not due:
620
- return session["access_token"]
621
- client_id = (data.get("registration") or {}).get("client_id", "")
622
- try:
623
- status, body = post(data["endpoints"]["token_endpoint"], {
624
- "grant_type": "refresh_token",
625
- "client_id": client_id,
626
- "refresh_token": session["refresh_token"],
627
- "resource": RESOURCE,
628
- })
629
- except connect.ConnectError as exc:
630
- raise Transient(f"Could not refresh the ChatGPT plan's sign-in: "
631
- f"{exc} The stored tokens are kept.") from None
632
- if status == 200 and body.get("access_token"):
633
- renewed = dict(session)
634
- earliest = body.get("earliest_refresh_at")
635
- renewed.update(
636
- access_token=body["access_token"],
637
- refresh_token=body.get("refresh_token")
638
- or session["refresh_token"],
639
- expires_at=moment + int(body.get("expires_in") or 3600),
640
- earliest_refresh_at=(float(earliest)
641
- if isinstance(earliest, (int, float))
642
- else None))
643
- if body.get("scope"):
644
- renewed["scopes"] = sorted(str(body["scope"]).split())
645
- renewed["plan_usage"] = PLAN_SCOPE in renewed["scopes"]
646
- data["session"] = renewed
647
- _write(data)
648
- return renewed["access_token"]
649
- error = str(body.get("error") or "")
650
- if error in UNUSABLE_REFRESH:
651
- data.pop("session", None)
652
- _write(data)
653
- logger.info("chatgpt: OpenAI ended the sign-in (%s)", error)
654
- raise SignedOut(f"OpenAI ended the ChatGPT plan's sign-in "
655
- f"({error}). /connect chatgpt signs in again.")
656
- raise Transient(f"Could not refresh the ChatGPT plan's sign-in "
657
- f"({error or f'HTTP {status}'}); the stored tokens "
658
- f"are kept and the next request tries again.")
659
-
660
-
661
- # ---------------------------------------------------------------------------
662
- # ---- Signing out --------------------------------------------------------------
663
- # ---------------------------------------------------------------------------
664
-
665
- def _revoke(endpoint: str, client_id: str, token: str, post: Post,
666
- sleep: Callable[[float], None],
667
- pauses: tuple = REVOKE_PAUSES_S) -> bool:
668
- """Revoke `token` at OpenAI; True only on its 200 (CG9).
669
-
670
- A network failure or a 5xx is tried again after each pause; any other
671
- answer is final. OpenAI answers 200 for a token that was already
672
- invalid too, so 200 means "not usable now" either way.
673
- """
674
- for pause in pauses:
675
- if pause:
676
- sleep(pause)
677
- try:
678
- status, _ = post(endpoint, {"token": token,
679
- "token_type_hint": "refresh_token",
680
- "client_id": client_id})
681
- except connect.ConnectError:
682
- continue
683
- if status == 200:
684
- return True
685
- if status < 500:
686
- return False
687
- return False
688
-
689
-
690
- def sign_out(*, forget: bool = False, post: Optional[Post] = None,
691
- sleep: Callable[[float], None] = time.sleep) -> Optional[bool]:
692
- """Revoke the refresh token, then forget the session (CG9, CG12).
693
-
694
- True when OpenAI confirmed the revocation, False when it could not be
695
- confirmed, None when there was no session to end. The local tokens are
696
- cleared in every case -- an unconfirmed revocation is reported, not
697
- retried forever -- and AFTER the attempt, so a process that dies
698
- mid-way still holds a token the next `/disconnect` can revoke.
699
-
700
- `forget` also drops the registration, so the next sign-in registers
701
- afresh and may be another account. The host id stays: it names this
702
- install, not an account.
703
- """
704
- post = post or connect.post_form
705
- with _locked():
706
- data = _read()
707
- session = data.get("session")
708
- confirmed = None
709
- if session:
710
- registration = data.get("registration") or {}
711
- confirmed = _revoke(
712
- (data.get("endpoints") or {}).get("revocation_endpoint", ""),
713
- registration.get("client_id", ""), session["refresh_token"],
714
- post, sleep)
715
- data.pop("session", None)
716
- if forget:
717
- data.pop("registration", None)
718
- if session or forget:
719
- _write(data)
720
- logger.info("chatgpt: signed out; revocation confirmed %s, registration "
721
- "%s", confirmed, "dropped" if forget else "kept")
722
- return confirmed
723
-
724
-
725
- # ---------------------------------------------------------------------------
726
- # ---- Status -------------------------------------------------------------------
727
- # ---------------------------------------------------------------------------
728
-
729
- @dataclass(frozen=True)
730
- class Status:
731
- """What the token file says, without a secret in it."""
732
-
733
- signed_in: bool
734
- plan_usage: bool
735
- registered: bool
736
- expires_at: Optional[float]
737
-
738
-
739
- def status() -> Status:
740
- """A read without the lock: the file is only ever replaced whole."""
741
- data = _read()
742
- session = data.get("session") or {}
743
- return Status(signed_in=bool(session.get("refresh_token")),
744
- plan_usage=bool(session.get("plan_usage")),
745
- registered=bool((data.get("registration") or {})
746
- .get("client_id")),
747
- expires_at=session.get("expires_at"))
1
+ """The ChatGPT plan's credential: signing in, staying signed in, signing out
2
+ (ROADMAP_v3 §83 slice 1; CG4-CG6, CG9, CG10, CG12).
3
+
4
+ OpenAI's Sign in with ChatGPT lets a Plus or Pro subscriber spend their plan
5
+ inside an open-source app that runs locally, which is the test HD5 set for
6
+ any sign-in: the provider's own documentation invites the third-party app
7
+ in. A remotely hosted app needs OpenAI's interest form first, so nothing
8
+ here runs on a hosted deployment (CG1); the TUI refuses before it gets here.
9
+
10
+ WHAT IS HERE AND WHAT IS NOT. Everything about the credential that is not
11
+ drawing: the registration OpenAI makes during the first sign-in, the
12
+ one-shot listener its redirect comes back to, the code exchange, the ID
13
+ token check, the token file, refreshing it, and revoking it. The TUI owns
14
+ the asking and the words; `core/connect.py` owns the preset; slice 2's
15
+ Responses path in `core/client.py` is the only caller of `access_token()`,
16
+ which the openai SDK calls before every request (CG21).
17
+
18
+ WHAT SLICE 0 MEASURED THAT THIS RELIES ON, on the owner's account
19
+ (batches 181-183): the callback carries `client_id`, `code`, `scope` and
20
+ `state`; access and ID tokens last 3600 s; the ID token is RS256 with a
21
+ `kid`; `earliest_refresh_at` is epoch seconds about six minutes before
22
+ expiry and is advice rather than a floor; a refresh rotates the refresh
23
+ token; revocation answers an empty 200 and kills the access token at once.
24
+
25
+ THE TOKEN FILE (CG4) is `chatgpt_auth.json` beside `providers.json`, 0600
26
+ and written atomically, and every read-modify-write of it happens under one
27
+ lock held across threads AND processes, because a refresh token rotates:
28
+ two harness processes refreshing at once would each spend the same one. The
29
+ lock is the operating system's (`fcntl.flock`, `msvcrt.locking`) on an
30
+ empty sidecar file, so a process that dies holding it releases it.
31
+
32
+ NOTHING HERE LOGS A TOKEN, A CODE OR A VERIFIER. Errors carry an HTTP status
33
+ and OpenAI's error code, never a body.
34
+
35
+ NO HTTP LIBRARY IS IMPORTED AT MODULE SCOPE, for `core/connect.py`'s reason:
36
+ every network call goes through a `post` or `get` callable the caller may
37
+ replace, and the defaults are that module's.
38
+ """
39
+
40
+ from __future__ import annotations
41
+
42
+ import base64
43
+ import hashlib
44
+ import hmac
45
+ import http.server
46
+ import logging
47
+ import os
48
+ import secrets
49
+ import threading
50
+ import time
51
+ import uuid
52
+ from collections.abc import Callable
53
+ from contextlib import contextmanager
54
+ from dataclasses import dataclass, field
55
+ from typing import Optional
56
+ from urllib.parse import parse_qsl, urlencode, urlsplit
57
+
58
+ import credentials
59
+ from core import connect
60
+ from json_store import read_versioned, write_json_atomic
61
+
62
+ logger = logging.getLogger(__name__)
63
+
64
+ ISSUER = "https://auth.openai.com"
65
+ RESOURCE = "https://api.openai.com/v1"
66
+ SCOPE = ("openid profile email offline_access resource.invoke "
67
+ "chatgpt.tokens.use.direct")
68
+ PLAN_SCOPE = "chatgpt.tokens.use.direct"
69
+ DYNAMIC_CLIENT = "dynamic_agent_client"
70
+ # What OpenAI shows on its consent page and in ChatGPT's connected apps: the
71
+ # app's own title, as its page asks (CG6).
72
+ AGENT_NAME = "Venastine Research Harness"
73
+ CALLBACK_PATH = "/auth/callback"
74
+ # Read by the owner from ChatGPT on 2026-10-26 (slice 0); no API reports it.
75
+ USAGE_URL = "https://chatgpt.com/settings/usage?tab=overview"
76
+ # CG1 in one sentence, wherever a hosted deployment meets the plan:
77
+ # /connect, /model, /critic and the launch warning (batch 195). It moved
78
+ # here from tui/app.py so credentials.py can say it too.
79
+ LOCAL_ONLY = (
80
+ "The ChatGPT plan signs in on a local install only: OpenAI offers it to "
81
+ "open-source apps running on your own machine, and its sign-in comes "
82
+ "back to 127.0.0.1, which a hosted deployment is not.")
83
+
84
+ AUTH_FILE = "chatgpt_auth.json"
85
+ STORE_VERSION = 1
86
+ # How long a sign-in waits for the browser to come back (CG5).
87
+ SIGN_IN_WAIT_S = 600
88
+ # Refresh this long before expiry at the latest, whatever
89
+ # `earliest_refresh_at` says.
90
+ REFRESH_MARGIN_S = 300
91
+ # How long to wait for another process's hold on the token file.
92
+ LOCK_WAIT_S = 30
93
+ # Pauses before each revocation attempt: the first is immediate.
94
+ REVOKE_PAUSES_S = (0, 2, 5)
95
+
96
+ # OpenAI's codes for a refresh token that will never work again. Anything
97
+ # else -- a network failure, a 5xx, a code not on this list -- keeps every
98
+ # stored token (CG10).
99
+ UNUSABLE_REFRESH = frozenset({
100
+ "invalid_grant", "invalid_refresh_token", "token_expired",
101
+ "refresh_token_expired", "refresh_token_invalidated",
102
+ "refresh_token_reused",
103
+ })
104
+
105
+ Post = Callable[[str, dict], tuple[int, dict]]
106
+ Get = Callable[[str], tuple[int, dict]]
107
+
108
+
109
+ class ChatGPTAuthError(connect.ConnectError):
110
+ """A sign-in step that cannot go on. The message is safe to show."""
111
+
112
+
113
+ class SignedOut(ChatGPTAuthError):
114
+ """There is no usable sign-in: never made, signed out, or ended by OpenAI."""
115
+
116
+
117
+ class Transient(ChatGPTAuthError):
118
+ """A refresh failed for a reason that may pass; every token was kept."""
119
+
120
+
121
+ # ---------------------------------------------------------------------------
122
+ # ---- The token file and its lock --------------------------------------------
123
+ # ---------------------------------------------------------------------------
124
+
125
+ def auth_path() -> str:
126
+ """`chatgpt_auth.json` beside `providers.json`, wherever that is.
127
+
128
+ Read through the module at call time, as `credentials` itself is, so a
129
+ test's monkeypatch of `credentials.LLM_PROVIDERS_FILE` and a user's
130
+ AGENT_PROVIDERS_FILE both move this file with it (#24).
131
+ """
132
+ return os.path.join(os.path.dirname(credentials.LLM_PROVIDERS_FILE),
133
+ AUTH_FILE)
134
+
135
+
136
+ def _read() -> dict:
137
+ data = read_versioned(auth_path(), STORE_VERSION,
138
+ "treating the ChatGPT plan as signed out.")
139
+ return data or {"version": STORE_VERSION}
140
+
141
+
142
+ def _write(data: dict) -> None:
143
+ # 0600 at creation, for credentials._write_secret_json's reason: these
144
+ # are bearer tokens for a paid plan.
145
+ data["version"] = STORE_VERSION
146
+ write_json_atomic(auth_path(), data, mode=0o600, indent=2)
147
+
148
+
149
+ if os.name == "nt":
150
+ import msvcrt
151
+
152
+ def _try_lock(fd: int) -> bool:
153
+ os.lseek(fd, 0, os.SEEK_SET)
154
+ try:
155
+ msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
156
+ except OSError:
157
+ return False
158
+ return True
159
+
160
+ def _unlock(fd: int) -> None:
161
+ os.lseek(fd, 0, os.SEEK_SET)
162
+ msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
163
+ else:
164
+ import fcntl
165
+
166
+ def _try_lock(fd: int) -> bool:
167
+ try:
168
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
169
+ except OSError:
170
+ return False
171
+ return True
172
+
173
+ def _unlock(fd: int) -> None:
174
+ fcntl.flock(fd, fcntl.LOCK_UN)
175
+
176
+
177
+ _THREAD_LOCK = threading.RLock()
178
+ _HELD = threading.local()
179
+
180
+
181
+ @contextmanager
182
+ def _locked():
183
+ """Hold the token file against every other thread and process (CG4).
184
+
185
+ Re-entrant within a thread: an OS lock taken twice by one process on two
186
+ descriptors deadlocks on POSIX, so a nested `with` only counts.
187
+ """
188
+ with _THREAD_LOCK:
189
+ depth = getattr(_HELD, "depth", 0)
190
+ if depth:
191
+ _HELD.depth = depth + 1
192
+ try:
193
+ yield
194
+ finally:
195
+ _HELD.depth = depth
196
+ return
197
+ path = auth_path() + ".lock"
198
+ parent = os.path.dirname(path)
199
+ if parent:
200
+ os.makedirs(parent, exist_ok=True)
201
+ fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o600)
202
+ try:
203
+ deadline = time.monotonic() + LOCK_WAIT_S
204
+ while not _try_lock(fd):
205
+ if time.monotonic() >= deadline:
206
+ raise Transient(
207
+ "Another Venastine process is holding the ChatGPT "
208
+ "plan's token file; try again in a moment.")
209
+ time.sleep(0.05)
210
+ _HELD.depth = 1
211
+ try:
212
+ yield
213
+ finally:
214
+ _HELD.depth = 0
215
+ _unlock(fd)
216
+ finally:
217
+ os.close(fd)
218
+
219
+
220
+ # ---------------------------------------------------------------------------
221
+ # ---- Discovery ----------------------------------------------------------------
222
+ # ---------------------------------------------------------------------------
223
+
224
+ def discover(get: Optional[Get] = None) -> dict:
225
+ """The four endpoints, from OpenAI's discovery document, checked.
226
+
227
+ The issuer must be OpenAI's and every endpoint https on its host: a
228
+ document naming somewhere else is refused rather than followed. The
229
+ hosted bridge's `deploy/hosted/sign_in.discover` makes the same checks
230
+ for ModelScope; it is not imported because `deploy/` is not shipped to
231
+ npm.
232
+ """
233
+ get = get or connect.get_json
234
+ status, doc = get(f"{ISSUER}/.well-known/openid-configuration")
235
+ if status != 200:
236
+ raise ChatGPTAuthError(
237
+ f"OpenAI's sign-in configuration answered HTTP {status}.")
238
+ if doc.get("issuer") != ISSUER:
239
+ raise ChatGPTAuthError(
240
+ "OpenAI's sign-in configuration names another issuer; nothing "
241
+ "was connected.")
242
+ host = urlsplit(ISSUER).hostname
243
+ endpoints = {}
244
+ for name in ("authorization_endpoint", "token_endpoint",
245
+ "revocation_endpoint", "jwks_uri"):
246
+ url = doc.get(name) or ""
247
+ parts = urlsplit(url)
248
+ if parts.scheme != "https" or parts.hostname != host:
249
+ raise ChatGPTAuthError(
250
+ f"OpenAI's sign-in configuration gives no usable {name}; "
251
+ f"nothing was connected.")
252
+ endpoints[name] = url
253
+ return endpoints
254
+
255
+
256
+ # ---------------------------------------------------------------------------
257
+ # ---- Signing in ---------------------------------------------------------------
258
+ # ---------------------------------------------------------------------------
259
+
260
+ class _Listener:
261
+ """The one-shot server OpenAI's redirect comes back to (CG5).
262
+
263
+ 127.0.0.1 on a free port, `/auth/callback` only, and only an answer
264
+ whose `state` matches: anything else is told no and changes nothing.
265
+ The first matching answer wins. The request line is never logged,
266
+ because it is where the authorization code arrives.
267
+ """
268
+
269
+ def __init__(self, state: str):
270
+ self.state = state
271
+ self.params: Optional[dict] = None
272
+ self.answered = threading.Event()
273
+ listener = self
274
+
275
+ class Handler(http.server.BaseHTTPRequestHandler):
276
+ def log_message(self, *args):
277
+ pass
278
+
279
+ def do_GET(self):
280
+ parts = urlsplit(self.path)
281
+ if parts.path != CALLBACK_PATH:
282
+ self._reply(404, "Not here.")
283
+ return
284
+ params = dict(parse_qsl(parts.query))
285
+ if not hmac.compare_digest(params.get("state", ""),
286
+ listener.state):
287
+ self._reply(400, "This answer belongs to another "
288
+ "sign-in.")
289
+ return
290
+ if listener.answered.is_set():
291
+ self._reply(400, "This sign-in was already answered.")
292
+ return
293
+ listener.params = params
294
+ listener.answered.set()
295
+ self._reply(200, "Done. You can close this tab and go back "
296
+ "to Venastine.")
297
+
298
+ def _reply(self, code: int, text: str) -> None:
299
+ body = text.encode("utf-8")
300
+ self.send_response(code)
301
+ self.send_header("Content-Type", "text/plain; charset=utf-8")
302
+ self.send_header("Content-Length", str(len(body)))
303
+ self.end_headers()
304
+ self.wfile.write(body)
305
+
306
+ self._server = http.server.HTTPServer(("127.0.0.1", 0), Handler)
307
+ self.port = self._server.server_address[1]
308
+ self._closed = False
309
+ threading.Thread(target=self._server.serve_forever,
310
+ name="chatgpt-sign-in", daemon=True).start()
311
+
312
+ def close(self) -> None:
313
+ if self._closed:
314
+ return
315
+ self._closed = True
316
+ self._server.shutdown()
317
+ self._server.server_close()
318
+
319
+
320
+ @dataclass
321
+ class SignIn:
322
+ """One sign-in in progress. `close()` it whichever way it ends."""
323
+
324
+ url: str
325
+ redirect_uri: str
326
+ state: str = field(repr=False)
327
+ nonce: str = field(repr=False)
328
+ verifier: str = field(repr=False)
329
+ endpoints: dict = field(repr=False)
330
+ listener: _Listener = field(repr=False)
331
+
332
+ def wait(self, timeout: float) -> Optional[dict]:
333
+ """The callback's parameters, or None if none came in time."""
334
+ if self.listener.answered.wait(timeout):
335
+ return self.listener.params
336
+ return None
337
+
338
+ def close(self) -> None:
339
+ self.listener.close()
340
+
341
+
342
+ def _b64url(raw: bytes) -> str:
343
+ return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
344
+
345
+
346
+ def start(*, get: Optional[Get] = None) -> SignIn:
347
+ """Begin a sign-in: the URL to open, and the listener waiting for it.
348
+
349
+ The host id is made once per install and kept (CG6). A saved
350
+ registration's client id is sent when there is one; otherwise
351
+ `dynamic_agent_client` and the app's name, which is how OpenAI
352
+ registers the app during the first sign-in (CG12).
353
+ """
354
+ endpoints = discover(get)
355
+ with _locked():
356
+ data = _read()
357
+ if not data.get("host_id"):
358
+ data["host_id"] = f"urn:uuid:{uuid.uuid4()}"
359
+ _write(data)
360
+ host_id = data["host_id"]
361
+ saved = (data.get("registration") or {}).get("client_id")
362
+
363
+ verifier = _b64url(secrets.token_bytes(64))
364
+ challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
365
+ state = secrets.token_urlsafe(32)
366
+ nonce = secrets.token_urlsafe(32)
367
+ listener = _Listener(state)
368
+ redirect_uri = f"http://127.0.0.1:{listener.port}{CALLBACK_PATH}"
369
+ query = {"client_id": saved or DYNAMIC_CLIENT}
370
+ if not saved:
371
+ query["agent_name_hint"] = AGENT_NAME
372
+ query.update({
373
+ "ext_agent_host_id": host_id,
374
+ "response_type": "code",
375
+ "redirect_uri": redirect_uri,
376
+ "scope": SCOPE,
377
+ "resource": RESOURCE,
378
+ "state": state,
379
+ "nonce": nonce,
380
+ "code_challenge": challenge,
381
+ "code_challenge_method": "S256",
382
+ })
383
+ url = f"{endpoints['authorization_endpoint']}?{urlencode(query)}"
384
+ return SignIn(url, redirect_uri, state, nonce, verifier, endpoints,
385
+ listener)
386
+
387
+
388
+ def pasted_params(sign_in: SignIn, text: str) -> dict:
389
+ """The callback's parameters from an address the person pasted (CG5).
390
+
391
+ For a browser on another machine, which cannot reach this listener: the
392
+ address it ended on is the same redirect, checked the same way --
393
+ exactly this sign-in's host, port and path, and its `state`.
394
+ """
395
+ parts = urlsplit((text or "").strip())
396
+ expected = urlsplit(sign_in.redirect_uri)
397
+ if (parts.scheme, parts.hostname, parts.port, parts.path) != (
398
+ expected.scheme, expected.hostname, expected.port, expected.path):
399
+ raise ChatGPTAuthError(
400
+ f"That is not the address this sign-in ends on; it starts with "
401
+ f"{sign_in.redirect_uri}?")
402
+ params = dict(parse_qsl(parts.query))
403
+ if not hmac.compare_digest(params.get("state", ""), sign_in.state):
404
+ raise ChatGPTAuthError(
405
+ "That address belongs to another sign-in. /connect chatgpt "
406
+ "starts a fresh one.")
407
+ return params
408
+
409
+
410
+ @dataclass(frozen=True)
411
+ class Completed:
412
+ """How a sign-in ended. `notice_due` is CG8's one-time notice."""
413
+
414
+ plan_usage: bool
415
+ notice_due: bool
416
+
417
+
418
+ def verify_id_token(token: str, client_id: str, nonce: str, jwks_uri: str,
419
+ *, get: Optional[Get] = None) -> dict:
420
+ """The ID token's claims, once it is shown to be OpenAI's (CG6).
421
+
422
+ RS256 and nothing else -- the algorithm is pinned before a key is
423
+ chosen, so a token claiming `none` or an HMAC is refused rather than
424
+ checked against a public key used as a secret. Then the signature
425
+ against the published keys, the issuer, the audience (this install's
426
+ client id), expiry, and the nonce this sign-in sent.
427
+ """
428
+ import jwt
429
+
430
+ get = get or connect.get_json
431
+ if not token:
432
+ raise ChatGPTAuthError("OpenAI sent no ID token; nothing was "
433
+ "connected.")
434
+ try:
435
+ header = jwt.get_unverified_header(token)
436
+ except jwt.PyJWTError:
437
+ raise ChatGPTAuthError("OpenAI's ID token is unreadable; nothing was "
438
+ "connected.") from None
439
+ if header.get("alg") != "RS256":
440
+ raise ChatGPTAuthError(
441
+ f"OpenAI's ID token is signed with {header.get('alg')!r}, not "
442
+ f"RS256; nothing was connected.")
443
+ status, jwks = get(jwks_uri)
444
+ if status != 200:
445
+ raise ChatGPTAuthError(
446
+ f"OpenAI's signing keys answered HTTP {status}; nothing was "
447
+ f"connected.")
448
+ try:
449
+ keys = jwt.PyJWKSet.from_dict(jwks).keys
450
+ except jwt.PyJWTError:
451
+ raise ChatGPTAuthError("OpenAI's signing keys are unreadable; nothing "
452
+ "was connected.") from None
453
+ kid = header.get("kid")
454
+ matching = [k for k in keys if k.key_id == kid] if kid else list(keys)
455
+ if not matching:
456
+ raise ChatGPTAuthError("No published OpenAI key matches the ID token; "
457
+ "nothing was connected.")
458
+ try:
459
+ claims = jwt.decode(
460
+ token, matching[0].key, algorithms=["RS256"], audience=client_id,
461
+ issuer=ISSUER, leeway=60,
462
+ options={"require": ["exp", "iat", "iss", "aud", "sub"]})
463
+ except jwt.PyJWTError as exc:
464
+ raise ChatGPTAuthError(
465
+ f"OpenAI's ID token did not verify ({type(exc).__name__}); "
466
+ f"nothing was connected.") from None
467
+ if not hmac.compare_digest(str(claims.get("nonce", "")), nonce):
468
+ raise ChatGPTAuthError("OpenAI's ID token answers another sign-in; "
469
+ "nothing was connected.")
470
+ return claims
471
+
472
+
473
+ def _session_from(body: dict, granted: list, now: float) -> dict:
474
+ earliest = body.get("earliest_refresh_at")
475
+ return {
476
+ "access_token": body["access_token"],
477
+ "refresh_token": body["refresh_token"],
478
+ "expires_at": now + int(body.get("expires_in") or 3600),
479
+ "earliest_refresh_at": (float(earliest)
480
+ if isinstance(earliest, (int, float))
481
+ else None),
482
+ "scopes": granted,
483
+ "plan_usage": PLAN_SCOPE in granted,
484
+ }
485
+
486
+
487
+ def complete(sign_in: SignIn, params: dict, *, post: Optional[Post] = None,
488
+ get: Optional[Get] = None,
489
+ now: Callable[[], float] = time.time) -> Completed:
490
+ """Trade the callback's code for tokens, check them, and store them.
491
+
492
+ ONE ACCOUNT PER INSTALL (CG12): a saved registration's client id is
493
+ what the exchange uses, and a callback naming a different one -- a
494
+ different ChatGPT account -- is refused, as OpenAI's page says to.
495
+ `/disconnect chatgpt --forget` is how the install changes account.
496
+
497
+ A sign-in that did not grant the plan scope is still kept, with
498
+ `plan_usage` false, and said so (CG6). A previous session's refresh
499
+ token is revoked once the new one is stored, so a second sign-in does
500
+ not leave a first one alive at OpenAI.
501
+ """
502
+ post = post or connect.post_form
503
+ if not hmac.compare_digest(params.get("state", ""), sign_in.state):
504
+ raise ChatGPTAuthError("That answer belongs to another sign-in.")
505
+ if params.get("error"):
506
+ if params["error"] == "access_denied":
507
+ raise ChatGPTAuthError("The sign-in was declined at OpenAI; "
508
+ "nothing was connected.")
509
+ raise ChatGPTAuthError(f"OpenAI ended the sign-in "
510
+ f"({params['error']}); nothing was connected.")
511
+ code = params.get("code")
512
+ if not code:
513
+ raise ChatGPTAuthError("OpenAI's answer carried no code; nothing was "
514
+ "connected.")
515
+ issued = params.get("client_id") or ""
516
+ with _locked():
517
+ saved = (_read().get("registration") or {}).get("client_id")
518
+ if saved and issued and issued != saved:
519
+ raise ChatGPTAuthError(
520
+ "That sign-in was for a different ChatGPT account than this "
521
+ "install is registered to. /disconnect chatgpt --forget, then "
522
+ "/connect chatgpt, switches accounts.")
523
+ client_id = saved or issued
524
+ if not client_id:
525
+ raise ChatGPTAuthError("OpenAI's answer carried no client id; nothing "
526
+ "was connected.")
527
+
528
+ status, body = post(sign_in.endpoints["token_endpoint"], {
529
+ "grant_type": "authorization_code",
530
+ "client_id": client_id,
531
+ "code": code,
532
+ "code_verifier": sign_in.verifier,
533
+ "redirect_uri": sign_in.redirect_uri,
534
+ "resource": RESOURCE,
535
+ })
536
+ if (status != 200 or not body.get("access_token")
537
+ or not body.get("refresh_token")):
538
+ why = body.get("error") or f"HTTP {status}"
539
+ raise ChatGPTAuthError(
540
+ f"OpenAI did not accept the sign-in ({why}). /connect chatgpt "
541
+ f"starts a fresh one.")
542
+ claims = verify_id_token(body.get("id_token"), client_id, sign_in.nonce,
543
+ sign_in.endpoints["jwks_uri"], get=get)
544
+ granted = sorted(str(body.get("scope") or params.get("scope") or "")
545
+ .split())
546
+ session = _session_from(body, granted, now())
547
+ account = claims["sub"]
548
+
549
+ with _locked():
550
+ data = _read()
551
+ registration = data.get("registration") or {}
552
+ shown = (bool(registration.get("notice_shown"))
553
+ and registration.get("account") == account)
554
+ previous = data.get("session") or {}
555
+ data["registration"] = {"client_id": client_id, "account": account,
556
+ "notice_shown": shown}
557
+ data["endpoints"] = dict(sign_in.endpoints)
558
+ data["session"] = session
559
+ _write(data)
560
+ logger.info("chatgpt: signed in; plan usage %s", session["plan_usage"])
561
+
562
+ old = previous.get("refresh_token")
563
+ if old and old != session["refresh_token"]:
564
+ _revoke(sign_in.endpoints["revocation_endpoint"], client_id, old,
565
+ post, time.sleep, pauses=(0,))
566
+ return Completed(plan_usage=session["plan_usage"],
567
+ notice_due=session["plan_usage"] and not shown)
568
+
569
+
570
+ def mark_notice_shown() -> None:
571
+ """Record that CG8's one-time notice was shown to this account."""
572
+ with _locked():
573
+ data = _read()
574
+ registration = data.get("registration")
575
+ if registration:
576
+ registration["notice_shown"] = True
577
+ _write(data)
578
+
579
+
580
+ # ---------------------------------------------------------------------------
581
+ # ---- Staying signed in --------------------------------------------------------
582
+ # ---------------------------------------------------------------------------
583
+
584
+ def access_token(*, post: Optional[Post] = None,
585
+ now: Callable[[], float] = time.time,
586
+ replacing: Optional[str] = None) -> str:
587
+ """A current access token, refreshed first when it is due (CG4, CG10).
588
+
589
+ Due at `earliest_refresh_at`, or `REFRESH_MARGIN_S` before expiry,
590
+ whichever comes first. The refresh happens under the lock, on a file
591
+ read AFTER the lock was taken -- another process may already have
592
+ refreshed, and its replacement is then the token to use -- and the
593
+ replacement is written before it is returned, because the refresh token
594
+ it replaced is spent.
595
+
596
+ `replacing` is the token a request was just refused with, a 401
597
+ (batch 188): it makes the refresh due whatever the clock says, but only
598
+ while the file still holds that token. When it does not, another thread
599
+ or process has already replaced it, and the replacement is returned
600
+ without spending a second refresh.
601
+
602
+ A refresh OpenAI refuses as unusable clears the session and raises
603
+ `SignedOut`. Anything else -- a network failure, a 5xx, a code not on
604
+ `UNUSABLE_REFRESH` -- raises `Transient` and keeps every token.
605
+ """
606
+ post = post or connect.post_form
607
+ with _locked():
608
+ data = _read()
609
+ session = data.get("session")
610
+ if not session:
611
+ raise SignedOut("The ChatGPT plan is not signed in. /connect "
612
+ "chatgpt signs in.")
613
+ moment = now()
614
+ earliest = session.get("earliest_refresh_at")
615
+ due = (moment >= session["expires_at"] - REFRESH_MARGIN_S
616
+ or (earliest is not None and moment >= earliest)
617
+ or (replacing is not None
618
+ and session["access_token"] == replacing))
619
+ if not due:
620
+ return session["access_token"]
621
+ client_id = (data.get("registration") or {}).get("client_id", "")
622
+ try:
623
+ status, body = post(data["endpoints"]["token_endpoint"], {
624
+ "grant_type": "refresh_token",
625
+ "client_id": client_id,
626
+ "refresh_token": session["refresh_token"],
627
+ "resource": RESOURCE,
628
+ })
629
+ except connect.ConnectError as exc:
630
+ raise Transient(f"Could not refresh the ChatGPT plan's sign-in: "
631
+ f"{exc} The stored tokens are kept.") from None
632
+ if status == 200 and body.get("access_token"):
633
+ renewed = dict(session)
634
+ earliest = body.get("earliest_refresh_at")
635
+ renewed.update(
636
+ access_token=body["access_token"],
637
+ refresh_token=body.get("refresh_token")
638
+ or session["refresh_token"],
639
+ expires_at=moment + int(body.get("expires_in") or 3600),
640
+ earliest_refresh_at=(float(earliest)
641
+ if isinstance(earliest, (int, float))
642
+ else None))
643
+ if body.get("scope"):
644
+ renewed["scopes"] = sorted(str(body["scope"]).split())
645
+ renewed["plan_usage"] = PLAN_SCOPE in renewed["scopes"]
646
+ data["session"] = renewed
647
+ _write(data)
648
+ return renewed["access_token"]
649
+ error = str(body.get("error") or "")
650
+ if error in UNUSABLE_REFRESH:
651
+ data.pop("session", None)
652
+ _write(data)
653
+ logger.info("chatgpt: OpenAI ended the sign-in (%s)", error)
654
+ raise SignedOut(f"OpenAI ended the ChatGPT plan's sign-in "
655
+ f"({error}). /connect chatgpt signs in again.")
656
+ raise Transient(f"Could not refresh the ChatGPT plan's sign-in "
657
+ f"({error or f'HTTP {status}'}); the stored tokens "
658
+ f"are kept and the next request tries again.")
659
+
660
+
661
+ # ---------------------------------------------------------------------------
662
+ # ---- Signing out --------------------------------------------------------------
663
+ # ---------------------------------------------------------------------------
664
+
665
+ def _revoke(endpoint: str, client_id: str, token: str, post: Post,
666
+ sleep: Callable[[float], None],
667
+ pauses: tuple = REVOKE_PAUSES_S) -> bool:
668
+ """Revoke `token` at OpenAI; True only on its 200 (CG9).
669
+
670
+ A network failure or a 5xx is tried again after each pause; any other
671
+ answer is final. OpenAI answers 200 for a token that was already
672
+ invalid too, so 200 means "not usable now" either way.
673
+ """
674
+ for pause in pauses:
675
+ if pause:
676
+ sleep(pause)
677
+ try:
678
+ status, _ = post(endpoint, {"token": token,
679
+ "token_type_hint": "refresh_token",
680
+ "client_id": client_id})
681
+ except connect.ConnectError:
682
+ continue
683
+ if status == 200:
684
+ return True
685
+ if status < 500:
686
+ return False
687
+ return False
688
+
689
+
690
+ def sign_out(*, forget: bool = False, post: Optional[Post] = None,
691
+ sleep: Callable[[float], None] = time.sleep) -> Optional[bool]:
692
+ """Revoke the refresh token, then forget the session (CG9, CG12).
693
+
694
+ True when OpenAI confirmed the revocation, False when it could not be
695
+ confirmed, None when there was no session to end. The local tokens are
696
+ cleared in every case -- an unconfirmed revocation is reported, not
697
+ retried forever -- and AFTER the attempt, so a process that dies
698
+ mid-way still holds a token the next `/disconnect` can revoke.
699
+
700
+ `forget` also drops the registration, so the next sign-in registers
701
+ afresh and may be another account. The host id stays: it names this
702
+ install, not an account.
703
+ """
704
+ post = post or connect.post_form
705
+ with _locked():
706
+ data = _read()
707
+ session = data.get("session")
708
+ confirmed = None
709
+ if session:
710
+ registration = data.get("registration") or {}
711
+ confirmed = _revoke(
712
+ (data.get("endpoints") or {}).get("revocation_endpoint", ""),
713
+ registration.get("client_id", ""), session["refresh_token"],
714
+ post, sleep)
715
+ data.pop("session", None)
716
+ if forget:
717
+ data.pop("registration", None)
718
+ if session or forget:
719
+ _write(data)
720
+ logger.info("chatgpt: signed out; revocation confirmed %s, registration "
721
+ "%s", confirmed, "dropped" if forget else "kept")
722
+ return confirmed
723
+
724
+
725
+ # ---------------------------------------------------------------------------
726
+ # ---- Status -------------------------------------------------------------------
727
+ # ---------------------------------------------------------------------------
728
+
729
+ @dataclass(frozen=True)
730
+ class Status:
731
+ """What the token file says, without a secret in it."""
732
+
733
+ signed_in: bool
734
+ plan_usage: bool
735
+ registered: bool
736
+ expires_at: Optional[float]
737
+
738
+
739
+ def status() -> Status:
740
+ """A read without the lock: the file is only ever replaced whole."""
741
+ data = _read()
742
+ session = data.get("session") or {}
743
+ return Status(signed_in=bool(session.get("refresh_token")),
744
+ plan_usage=bool(session.get("plan_usage")),
745
+ registered=bool((data.get("registration") or {})
746
+ .get("client_id")),
747
+ expires_at=session.get("expires_at"))