conductor-lab 0.1.2__py3-none-any.whl

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 (64) hide show
  1. conductor_lab/__init__.py +3 -0
  2. conductor_lab/agent_lock.py +189 -0
  3. conductor_lab/api.py +505 -0
  4. conductor_lab/cli.py +1101 -0
  5. conductor_lab/families.json +250 -0
  6. conductor_lab/families.py +161 -0
  7. conductor_lab/file_lock.py +89 -0
  8. conductor_lab/forward_health.py +65 -0
  9. conductor_lab/forwarder.py +567 -0
  10. conductor_lab/grants.py +370 -0
  11. conductor_lab/grpc_budget.py +23 -0
  12. conductor_lab/health.py +294 -0
  13. conductor_lab/identity.py +117 -0
  14. conductor_lab/packages/__init__.py +1 -0
  15. conductor_lab/packages/cli.py +84 -0
  16. conductor_lab/packages/enrollment.py +27 -0
  17. conductor_lab/packages/health.py +57 -0
  18. conductor_lab/packages/install.py +148 -0
  19. conductor_lab/packages/models.py +213 -0
  20. conductor_lab/packages/runtime.py +280 -0
  21. conductor_lab/permissions.py +100 -0
  22. conductor_lab/py.typed +0 -0
  23. conductor_lab/qubic/__init__.py +1 -0
  24. conductor_lab/qubic/deadlines.py +81 -0
  25. conductor_lab/qubic/handler.py +685 -0
  26. conductor_lab/qubic/sender.py +375 -0
  27. conductor_lab/queue/__init__.py +4 -0
  28. conductor_lab/queue/admission.py +62 -0
  29. conductor_lab/queue/agent.py +722 -0
  30. conductor_lab/queue/clock.py +245 -0
  31. conductor_lab/queue/commands.py +141 -0
  32. conductor_lab/queue/delivery.py +264 -0
  33. conductor_lab/queue/delivery_http.py +112 -0
  34. conductor_lab/queue/enrolment.py +171 -0
  35. conductor_lab/queue/entries.py +392 -0
  36. conductor_lab/queue/grpc_handler.py +298 -0
  37. conductor_lab/queue/handlers.py +273 -0
  38. conductor_lab/queue/identity.py +228 -0
  39. conductor_lab/queue/journal.py +462 -0
  40. conductor_lab/queue/keychain.py +390 -0
  41. conductor_lab/queue/lab_runtime.py +202 -0
  42. conductor_lab/queue/locks.py +77 -0
  43. conductor_lab/queue/polling.py +252 -0
  44. conductor_lab/queue/proofs.py +95 -0
  45. conductor_lab/queue/registry.py +73 -0
  46. conductor_lab/queue/replies.py +279 -0
  47. conductor_lab/queue/runtime.py +805 -0
  48. conductor_lab/queue/served.py +280 -0
  49. conductor_lab/queue/sessions.py +381 -0
  50. conductor_lab/queue/timings.py +61 -0
  51. conductor_lab/queue_entry.py +406 -0
  52. conductor_lab/state.py +192 -0
  53. conductor_lab/target.py +99 -0
  54. conductor_lab/terminal.py +194 -0
  55. conductor_lab/user_cli.py +127 -0
  56. conductor_lab/user_queue.py +516 -0
  57. conductor_lab/user_router.py +166 -0
  58. conductor_lab/version.py +17 -0
  59. conductor_lab/web_clock.py +177 -0
  60. conductor_lab-0.1.2.dist-info/METADATA +125 -0
  61. conductor_lab-0.1.2.dist-info/RECORD +64 -0
  62. conductor_lab-0.1.2.dist-info/WHEEL +5 -0
  63. conductor_lab-0.1.2.dist-info/entry_points.txt +2 -0
  64. conductor_lab-0.1.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,3 @@
1
+ """Conductor jump-host agent."""
2
+
3
+ __version__ = "0.1.2"
@@ -0,0 +1,189 @@
1
+ """Track running lab agents so logout can stop them before signing out."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import signal
7
+ import sys
8
+ import time
9
+ from contextlib import contextmanager, suppress
10
+ from typing import TYPE_CHECKING
11
+
12
+ from conductor_lab.file_lock import lock, unlock
13
+ from conductor_lab.permissions import restrict_directory, restrict_file
14
+ from conductor_lab.state import state_path
15
+
16
+ if TYPE_CHECKING:
17
+ from collections.abc import Callable, Iterator
18
+ from pathlib import Path
19
+
20
+
21
+ def agent_lock_dir(config_dir: str | Path | None = None) -> Path:
22
+ """Return the directory holding one lock file per running agent."""
23
+ return state_path(config_dir).parent
24
+
25
+
26
+ @contextmanager
27
+ def hold_agent_lock(config_dir: str | Path | None = None) -> Iterator[Path]:
28
+ """Hold a per-process lock marking this agent as running.
29
+
30
+ Each agent writes its own ``agent-<pid>.lock`` file, so several agents can
31
+ share one saved login. The file is removed when the agent exits.
32
+ """
33
+ directory = agent_lock_dir(config_dir)
34
+ directory.mkdir(mode=0o700, parents=True, exist_ok=True)
35
+ restrict_directory(directory)
36
+ path = directory / f"agent-{os.getpid()}.lock"
37
+ while True:
38
+ descriptor = os.open(path, os.O_WRONLY | os.O_CREAT, 0o600)
39
+ lock_file = os.fdopen(descriptor, "w", encoding="utf-8")
40
+ restrict_file(path)
41
+ lock(lock_file.fileno(), wait=True)
42
+ held = os.fstat(lock_file.fileno())
43
+ try:
44
+ current = path.stat()
45
+ except FileNotFoundError:
46
+ current = None
47
+ if current is not None and (held.st_dev, held.st_ino) == (
48
+ current.st_dev,
49
+ current.st_ino,
50
+ ):
51
+ break
52
+ lock_file.close()
53
+ try:
54
+ lock_file.write(str(os.getpid()))
55
+ lock_file.flush()
56
+ yield path
57
+ finally:
58
+ if sys.platform == "win32":
59
+ unlock(lock_file.fileno())
60
+ lock_file.close()
61
+ with suppress(FileNotFoundError):
62
+ path.unlink()
63
+ lock_file.close()
64
+
65
+
66
+ @contextmanager
67
+ def hold_profile_lock(*, exclusive: bool) -> Iterator[None]:
68
+ """Allow concurrent agents but prevent switching credentials beneath them."""
69
+ directory = agent_lock_dir()
70
+ directory.mkdir(mode=0o700, parents=True, exist_ok=True)
71
+ restrict_directory(directory)
72
+ path = directory / "profile.lock"
73
+ with path.open("a", encoding="utf-8") as lock_file:
74
+ restrict_file(path)
75
+ try:
76
+ lock(lock_file.fileno(), shared=not exclusive, wait=False)
77
+ except BlockingIOError as error:
78
+ raise RuntimeError("Stop the running lab profile before switching labs.") from error
79
+ try:
80
+ if exclusive and any(not _try_clear_lock(p) for p in directory.glob("agent-*.lock")):
81
+ raise RuntimeError("Stop the running lab profile before switching labs.")
82
+ yield
83
+ finally:
84
+ unlock(lock_file.fileno())
85
+
86
+
87
+ def stop_running_agents(
88
+ timeout: float,
89
+ *,
90
+ sleep: Callable[[float], None] = time.sleep,
91
+ clock: Callable[[], float] = time.monotonic,
92
+ on_stop: Callable[[], None] | None = None,
93
+ signal_after: float = 0.0,
94
+ ) -> bool:
95
+ """Stop every process holding an agent lock and wait for it to exit.
96
+
97
+ Agents that exit on their own within ``signal_after`` are never signalled.
98
+ ``on_stop`` runs once just before the first SIGTERM is sent.
99
+
100
+ Returns:
101
+ Whether no running agents remain. ``False`` means at least one agent
102
+ could not be read or signalled or did not release its lock before
103
+ ``timeout``.
104
+ """
105
+ deadline = clock() + timeout
106
+ signal_at = clock() + min(signal_after, timeout)
107
+ running = list(agent_lock_dir().glob("agent-*.lock"))
108
+ while running and clock() < signal_at:
109
+ sleep(min(0.05, max(0.0, signal_at - clock())))
110
+ try:
111
+ running = [path for path in running if not _try_clear_lock(path)]
112
+ except PermissionError:
113
+ return False
114
+ busy: list[Path] = []
115
+ announced = False
116
+ for path in running:
117
+ try:
118
+ outcome = _stop_lock_holder(path, on_stop if not announced else None)
119
+ except PermissionError:
120
+ return False
121
+ announced = announced or outcome == "signalled"
122
+ if outcome != "clear":
123
+ busy.append(path)
124
+ while busy:
125
+ if clock() >= deadline:
126
+ return False
127
+ sleep(min(0.05, max(0.0, deadline - clock())))
128
+ try:
129
+ busy = [path for path in busy if not _try_clear_lock(path)]
130
+ except PermissionError:
131
+ return False
132
+ return True
133
+
134
+
135
+ def _stop_lock_holder(
136
+ path: Path,
137
+ before_signal: Callable[[], None] | None,
138
+ ) -> str:
139
+ """Clear one stale lock or SIGTERM the process holding it.
140
+
141
+ ``before_signal`` runs just before a SIGTERM is sent.
142
+
143
+ Returns:
144
+ ``clear`` when no running agent holds the file, ``held`` when an
145
+ agent may still release it, or ``signalled`` when a SIGTERM was sent.
146
+ """
147
+ if _try_clear_lock(path):
148
+ return "clear"
149
+ pid = _lock_pid(path)
150
+ if pid is None:
151
+ return "held"
152
+ if before_signal is not None:
153
+ before_signal()
154
+ try:
155
+ os.kill(pid, signal.SIGTERM)
156
+ except ProcessLookupError:
157
+ return "held" if not _try_clear_lock(path) else "clear"
158
+ return "signalled"
159
+
160
+
161
+ def _try_clear_lock(path: Path) -> bool:
162
+ """Remove a lock file once no process holds it. Return whether it is gone."""
163
+ try:
164
+ lock_file = path.open("r")
165
+ except FileNotFoundError:
166
+ return True
167
+ try:
168
+ try:
169
+ lock(lock_file.fileno(), wait=False)
170
+ except BlockingIOError:
171
+ return False
172
+ finally:
173
+ lock_file.close()
174
+ with suppress(FileNotFoundError):
175
+ path.unlink()
176
+ return True
177
+
178
+
179
+ def _lock_pid(path: Path) -> int | None:
180
+ """Read the process id recorded inside a held lock file."""
181
+ try:
182
+ text = path.read_text(encoding="utf-8").strip()
183
+ except OSError:
184
+ return None
185
+ try:
186
+ pid = int(text)
187
+ except ValueError:
188
+ return None
189
+ return pid if pid > 0 else None
conductor_lab/api.py ADDED
@@ -0,0 +1,505 @@
1
+ """HTTP client for the Control lab-agent API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ from dataclasses import dataclass, field
8
+ from typing import TYPE_CHECKING, cast
9
+
10
+ if TYPE_CHECKING:
11
+ from pathlib import Path
12
+
13
+ from conductor_lab.packages.models import PackageRef
14
+ from urllib.error import HTTPError
15
+ from urllib.parse import urljoin, urlsplit
16
+ from urllib.request import HTTPRedirectHandler, Request, build_opener
17
+
18
+ from conductor_lab.packages.enrollment import EnrollmentApproval
19
+
20
+ REQUEST_TIMEOUT_SECONDS = 10
21
+ HTTP_OK = 200
22
+ HTTP_ACCEPTED = 202
23
+ HTTP_GONE = 410
24
+ HTTP_REDIRECT_START = 300
25
+ HTTP_REDIRECT_END = 400
26
+
27
+
28
+ class ApiError(Exception):
29
+ """An HTTP error returned by the Conductor API."""
30
+
31
+ def __init__(self, status: int, message: str) -> None:
32
+ """Create an API error with its HTTP status and safe message."""
33
+ super().__init__(message)
34
+ self.status = status
35
+ self.message = message
36
+
37
+
38
+ class VercelProtectionError(ApiError):
39
+ """An HTTP response from Vercel Deployment Protection."""
40
+
41
+
42
+ def resolve_bypass_token(saved: str | None) -> str | None:
43
+ """Prefer a non-empty environment token, then the saved token."""
44
+ return os.environ.get("VERCEL_BYPASS_TOKEN") or saved or None
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class ConnectRequest:
49
+ """Device-code request details returned by the API."""
50
+
51
+ device_code: str
52
+ user_code: str
53
+ verification_uri: str
54
+ verification_uri_complete: str
55
+ expires_in: int
56
+ interval: int
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class ConnectPending:
61
+ """A device-code request that still awaits approval."""
62
+
63
+ interval: int
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class ConnectApproved:
68
+ """Approved connection details and the one-time agent token."""
69
+
70
+ agent_token: str
71
+ lab_id: str
72
+ lab_name: str
73
+ package_approval: EnrollmentApproval | None = field(default=None, repr=False)
74
+
75
+
76
+ @dataclass(frozen=True)
77
+ class ConnectExpired:
78
+ """A device-code request that has expired."""
79
+
80
+
81
+ ConnectResult = ConnectPending | ConnectApproved | ConnectExpired
82
+
83
+
84
+ @dataclass(frozen=True)
85
+ class IdentityTokens:
86
+ """A rotated refresh token and the access token issued with it."""
87
+
88
+ refresh_token: str = field(repr=False)
89
+ access_token: str = field(repr=False)
90
+ access_expires_at_ms: int
91
+ server_time_ms: int
92
+
93
+
94
+ @dataclass(frozen=True)
95
+ class QueueEnrolled:
96
+ """An accepted queue lab key with its first token pair."""
97
+
98
+ lab_id: str
99
+ lab_name: str
100
+ session_id: str
101
+ tokens: IdentityTokens
102
+ package_approval: EnrollmentApproval | None = field(default=None, repr=False)
103
+
104
+
105
+ QueueEnrolResult = ConnectPending | QueueEnrolled | ConnectExpired
106
+
107
+
108
+ @dataclass(frozen=True)
109
+ class Forward:
110
+ """A configured connection endpoint forwarded by the lab agent."""
111
+
112
+ id: str
113
+ connection_id: str
114
+ driver: str
115
+ address: str
116
+ port: int
117
+
118
+
119
+ class _NoRedirect(HTTPRedirectHandler):
120
+ """Never forward credentials through an HTTP redirect."""
121
+
122
+ def redirect_request(self, *_args: object, **_kwargs: object) -> None:
123
+ """Return no redirected request; urllib raises the original HTTP error."""
124
+
125
+
126
+ urlopen = build_opener(_NoRedirect()).open
127
+
128
+
129
+ class AgentApi:
130
+ """Call the public HTTP endpoints used by the jump-host agent."""
131
+
132
+ def __init__(
133
+ self,
134
+ server: str,
135
+ agent_token: str | None = None,
136
+ bypass_token: str | None = None,
137
+ ) -> None:
138
+ """Initialize an API client for a server and optional lab tokens."""
139
+ self.profile = "lab"
140
+ self.server = server.rstrip("/")
141
+ self.agent_token = agent_token
142
+ self.bypass_token = bypass_token
143
+
144
+ def start_connect(self, hostname: str) -> ConnectRequest:
145
+ """Request a device code for a new lab connection."""
146
+ status, result = self._request(
147
+ "POST",
148
+ "/api/agent/v1/connect",
149
+ {
150
+ "hostname": hostname,
151
+ **({"package_enrollment": True} if self.profile == "lab" else {}),
152
+ },
153
+ )
154
+ data = _as_object(result, status)
155
+ try:
156
+ return ConnectRequest(
157
+ device_code=_required_string(data, "device_code"),
158
+ user_code=_required_string(data, "user_code"),
159
+ verification_uri=_required_string(data, "verification_uri"),
160
+ verification_uri_complete=_required_string(
161
+ data,
162
+ "verification_uri_complete",
163
+ ),
164
+ expires_in=_required_int(data, "expires_in"),
165
+ interval=_required_int(data, "interval"),
166
+ )
167
+ except (TypeError, ValueError) as error:
168
+ raise ApiError(502, "Invalid connect response") from error
169
+
170
+ def poll_connect(self, device_code: str) -> ConnectResult:
171
+ """Poll a device-code request and return its current state."""
172
+ try:
173
+ status, result = self._request(
174
+ "POST",
175
+ "/api/agent/v1/connect/token",
176
+ {"device_code": device_code},
177
+ )
178
+ except ApiError as error:
179
+ if error.status == HTTP_GONE:
180
+ return ConnectExpired()
181
+ raise
182
+
183
+ data = _as_object(result, status)
184
+ state = data.get("status")
185
+ if status == HTTP_ACCEPTED and state == "pending":
186
+ return ConnectPending(interval=_optional_int(data, "interval", 5))
187
+ if status == HTTP_OK and state == "approved":
188
+ try:
189
+ return ConnectApproved(
190
+ agent_token=_required_string(data, "agent_token"),
191
+ lab_id=_required_string(data, "lab_id"),
192
+ lab_name=_required_string(data, "lab_name"),
193
+ package_approval=(
194
+ EnrollmentApproval.model_validate(data["package_approval"])
195
+ if data.get("package_approval") is not None
196
+ else None
197
+ ),
198
+ )
199
+ except (TypeError, ValueError) as error:
200
+ raise ApiError(502, "Invalid approval response") from error
201
+ raise ApiError(502, "Invalid connect polling response")
202
+
203
+ def enroll_queue(self, device_code: str, public_key: str) -> QueueEnrolResult:
204
+ """Claim an approved device code for a queue lab with a fresh public key."""
205
+ try:
206
+ status, result = self._request(
207
+ "POST",
208
+ "/api/lab/v1/identity/enroll",
209
+ {"device_code": device_code, "public_key": public_key},
210
+ )
211
+ except ApiError as error:
212
+ if error.status == HTTP_GONE:
213
+ return ConnectExpired()
214
+ raise
215
+ data = _as_object(result, status)
216
+ if status == HTTP_ACCEPTED and data.get("status") == "pending":
217
+ return ConnectPending(interval=_optional_int(data, "interval", 5))
218
+ if status != HTTP_OK or data.get("status") != "approved":
219
+ raise ApiError(502, "Invalid lab enrolment response")
220
+ try:
221
+ return QueueEnrolled(
222
+ lab_id=_required_string(data, "lab_id"),
223
+ lab_name=_required_string(data, "lab_name"),
224
+ session_id=_required_string(data, "session_id"),
225
+ tokens=_identity_tokens(data),
226
+ package_approval=(
227
+ EnrollmentApproval.model_validate(data["package_approval"])
228
+ if data.get("package_approval") is not None
229
+ else None
230
+ ),
231
+ )
232
+ except (TypeError, ValueError) as error:
233
+ raise ApiError(502, "Invalid lab enrolment response") from error
234
+
235
+ def identity_challenge(self, lab_id: str, session_id: str, purpose: str) -> str:
236
+ """Request the identity's single-use challenge for ``refresh`` or ``revoke``."""
237
+ status, result = self._request(
238
+ "POST",
239
+ "/api/lab/v1/identity/challenge",
240
+ {"lab_id": lab_id, "session_id": session_id, "purpose": purpose},
241
+ )
242
+ try:
243
+ return _required_string(_as_object(result, status), "challenge")
244
+ except TypeError as error:
245
+ raise ApiError(502, "Invalid lab identity challenge") from error
246
+
247
+ def refresh_identity(
248
+ self, lab_id: str, refresh_token: str, challenge: str, signature: str
249
+ ) -> IdentityTokens:
250
+ """Present a refresh token with a key proof and return the rotated pair."""
251
+ status, result = self._request(
252
+ "POST",
253
+ "/api/lab/v1/identity/refresh",
254
+ {
255
+ "lab_id": lab_id,
256
+ "refresh_token": refresh_token,
257
+ "challenge": challenge,
258
+ "signature": signature,
259
+ },
260
+ )
261
+ try:
262
+ return _identity_tokens(_as_object(result, status))
263
+ except TypeError as error:
264
+ raise ApiError(502, "Invalid lab identity refresh") from error
265
+
266
+ def log_out_identity(
267
+ self, lab_id: str, session_id: str, challenge: str, signature: str
268
+ ) -> None:
269
+ """Revoke the identity with a key proof; any non-2xx answer raises."""
270
+ status, result = self._request(
271
+ "POST",
272
+ "/api/lab/v1/identity/logout",
273
+ {
274
+ "lab_id": lab_id,
275
+ "session_id": session_id,
276
+ "challenge": challenge,
277
+ "signature": signature,
278
+ },
279
+ )
280
+ if _as_object(result, status).get("status") not in {"logged_out", "revoked"}:
281
+ raise ApiError(502, "Invalid lab identity logout")
282
+
283
+ def heartbeat(self, hostname: str, version: str) -> dict[str, object]:
284
+ """Send a heartbeat with the local hostname and agent version."""
285
+ status, result = self._request(
286
+ "POST",
287
+ "/api/agent/v1/heartbeat",
288
+ {
289
+ "hostname": hostname,
290
+ "agent_version": version,
291
+ },
292
+ authenticated=True,
293
+ )
294
+ response = _as_object(result, status)
295
+ _validate_heartbeat(response)
296
+ return response
297
+
298
+ def report_forward_health(self, reports: list[dict[str, object]]) -> dict[str, object]:
299
+ """Report health for approved IDs without adding discovered inventory."""
300
+ status, result = self._request(
301
+ "POST", "/api/agent/v1/forwards/health", {"connections": reports}, authenticated=True
302
+ )
303
+ return _as_object(result, status)
304
+
305
+ def download_package(self, reference: PackageRef, destination: Path) -> None:
306
+ """Fetch a private release through the authenticated Control broker, never GitHub auth."""
307
+ if self.agent_token is None:
308
+ raise ApiError(401, "Missing agent token")
309
+ headers = {"Authorization": f"Bearer {self.agent_token}"}
310
+ if self.bypass_token:
311
+ headers["x-vercel-protection-bypass"] = self.bypass_token
312
+ request = Request( # noqa: S310 - fixed authenticated Control origin, redirects forbidden.
313
+ f"{self.server}/api/agent/v1/packages/artifact?sha256={reference.sha256}",
314
+ headers=headers,
315
+ )
316
+ with urlopen(request, timeout=60) as response:
317
+ content = response.read(128 * 1024 * 1024 + 1)
318
+ if len(content) > 128 * 1024 * 1024:
319
+ raise ValueError("Instrument artifact exceeds size limit")
320
+ destination.write_bytes(content)
321
+
322
+ def list_packages(self) -> object:
323
+ """Fetch only configured package deployments approved for this lab agent."""
324
+ _, result = self._request("GET", "/api/agent/v1/packages", authenticated=True)
325
+ return result
326
+
327
+ def list_forwards(self) -> list[Forward]:
328
+ """Fetch configured connection forwards for this lab."""
329
+ status, result = self._request(
330
+ "GET",
331
+ "/api/agent/v1/forwards",
332
+ authenticated=True,
333
+ )
334
+ if not isinstance(result, list):
335
+ raise ApiError(502, "Invalid forwards response")
336
+
337
+ forwards: list[Forward] = []
338
+ for item in result:
339
+ data = _as_object(item, status)
340
+ if set(data) != {"id", "connection_id", "driver", "address", "port"}:
341
+ raise ApiError(502, "Invalid forwards response")
342
+ try:
343
+ forwards.append(
344
+ Forward(
345
+ id=_required_string(data, "id"),
346
+ connection_id=_required_string(data, "connection_id"),
347
+ driver=_required_string(data, "driver"),
348
+ address=_required_string(data, "address"),
349
+ port=_required_int(data, "port"),
350
+ ),
351
+ )
352
+ except (TypeError, ValueError) as error:
353
+ raise ApiError(502, "Invalid forwards response") from error
354
+ return forwards
355
+
356
+ def _request(
357
+ self,
358
+ method: str,
359
+ path: str,
360
+ payload: object | None = None,
361
+ *,
362
+ authenticated: bool = False,
363
+ ) -> tuple[int, object]:
364
+ if self.profile == "user":
365
+ path = path.replace("/api/agent/", "/api/user/")
366
+ headers = {"Accept": "application/json"}
367
+ if self.bypass_token:
368
+ headers["x-vercel-protection-bypass"] = self.bypass_token
369
+ if payload is not None:
370
+ headers["Content-Type"] = "application/json"
371
+ if authenticated:
372
+ if self.agent_token is None:
373
+ raise ApiError(401, "Missing agent token")
374
+ headers["Authorization"] = f"Bearer {self.agent_token}"
375
+
376
+ body = json.dumps(payload).encode() if payload is not None else None
377
+ request = Request( # noqa: S310
378
+ f"{self.server}{path}",
379
+ data=body,
380
+ headers=headers,
381
+ method=method,
382
+ )
383
+ try:
384
+ with urlopen(
385
+ request,
386
+ timeout=REQUEST_TIMEOUT_SECONDS,
387
+ ) as response:
388
+ return response.status, _decode_json(response.read())
389
+ except HTTPError as error:
390
+ if _is_vercel_protection(error):
391
+ message = (
392
+ f"Vercel Deployment Protection rejected VERCEL_BYPASS_TOKEN for {self.server}; "
393
+ "check it matches the project's bypass secret."
394
+ if self.bypass_token
395
+ else f"The app at {self.server} is behind Vercel Deployment Protection. "
396
+ "Set VERCEL_BYPASS_TOKEN to the project's Protection Bypass for Automation "
397
+ "secret, then run `conductor login` again."
398
+ )
399
+ raise VercelProtectionError(error.code, message) from error
400
+ try:
401
+ response = _decode_json(error.read())
402
+ except ApiError:
403
+ response = None
404
+ if isinstance(response, dict) and isinstance(response.get("error"), str):
405
+ message = cast("str", response["error"])
406
+ else:
407
+ message = f"HTTP {error.code}"
408
+ raise ApiError(error.code, message) from error
409
+
410
+
411
+ def _is_vercel_protection(error: HTTPError) -> bool:
412
+ """Recognize Vercel's HTML protection page and SSO redirects."""
413
+ headers = error.headers
414
+ content_type = headers.get("Content-Type", "") if headers is not None else ""
415
+ media_type = content_type.partition(";")[0].strip().lower()
416
+ is_json = media_type == "application/json" or media_type.endswith("+json")
417
+ server = headers.get("Server", "") if headers is not None else ""
418
+ has_vercel_id = headers is not None and headers.get("x-vercel-id") is not None
419
+ if error.code in {401, 403} and not is_json and ("vercel" in server.lower() or has_vercel_id):
420
+ return True
421
+ location = headers.get("Location") if headers is not None else None
422
+ if HTTP_REDIRECT_START <= error.code < HTTP_REDIRECT_END and location:
423
+ try:
424
+ host = urlsplit(urljoin(error.url, location)).hostname
425
+ except ValueError:
426
+ return False
427
+ return host == "vercel.com" or bool(host and host.endswith(".vercel.com"))
428
+ return False
429
+
430
+
431
+ def _decode_json(body: bytes) -> object:
432
+ try:
433
+ return json.loads(body)
434
+ except (json.JSONDecodeError, UnicodeDecodeError) as error:
435
+ raise ApiError(502, "Invalid JSON response") from error
436
+
437
+
438
+ def _as_object(value: object, status: int) -> dict[str, object]:
439
+ if not isinstance(value, dict):
440
+ raise ApiError(502, f"Invalid JSON response (HTTP {status})")
441
+ return cast("dict[str, object]", value)
442
+
443
+
444
+ def _required_string(data: dict[str, object], key: str) -> str:
445
+ value = data.get(key)
446
+ if not isinstance(value, str) or not value:
447
+ raise TypeError(key)
448
+ return value
449
+
450
+
451
+ def _required_int(data: dict[str, object], key: str) -> int:
452
+ value = data.get(key)
453
+ if not isinstance(value, int) or isinstance(value, bool):
454
+ raise TypeError(key)
455
+ return value
456
+
457
+
458
+ def _identity_tokens(data: dict[str, object]) -> IdentityTokens:
459
+ refresh_token = _required_string(data, "refresh_token")
460
+ access_token = _required_string(data, "access_token")
461
+ if not refresh_token.startswith("lrt_") or not access_token.startswith("lat1."):
462
+ raise TypeError("token")
463
+ return IdentityTokens(
464
+ refresh_token=refresh_token,
465
+ access_token=access_token,
466
+ access_expires_at_ms=_required_int(data, "access_expires_at_ms"),
467
+ server_time_ms=_required_int(data, "server_time_ms"),
468
+ )
469
+
470
+
471
+ def _optional_int(data: dict[str, object], key: str, default: int) -> int:
472
+ value = data.get(key)
473
+ if value is None:
474
+ return default
475
+ if not isinstance(value, int) or isinstance(value, bool):
476
+ raise ApiError(502, "Invalid connect polling response")
477
+ return value
478
+
479
+
480
+ def _validate_heartbeat(data: dict[str, object]) -> None:
481
+ """Validate optional grant and revocation fields in a heartbeat."""
482
+ grant_keys = data.get("grant_keys")
483
+ if grant_keys is not None and (
484
+ not isinstance(grant_keys, list)
485
+ or any(
486
+ not isinstance(item, dict)
487
+ or not isinstance(item.get("kid"), str)
488
+ or not isinstance(item.get("public_key"), str)
489
+ for item in grant_keys
490
+ )
491
+ ):
492
+ raise ApiError(502, "Invalid heartbeat response")
493
+
494
+ active_job_ids = data.get("active_job_ids")
495
+ if active_job_ids is not None and (
496
+ not isinstance(active_job_ids, list)
497
+ or any(not isinstance(job_id, str) for job_id in active_job_ids)
498
+ ):
499
+ raise ApiError(502, "Invalid heartbeat response")
500
+
501
+ server_time_ms = data.get("server_time_ms")
502
+ if server_time_ms is not None and (
503
+ not isinstance(server_time_ms, int) or isinstance(server_time_ms, bool)
504
+ ):
505
+ raise ApiError(502, "Invalid heartbeat response")