nkx-runtime 2.2.0__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.

Potentially problematic release.


This version of nkx-runtime might be problematic. Click here for more details.

@@ -0,0 +1,384 @@
1
+ """Self-registration for the registered-instance KEK exchange (Part 1).
2
+
3
+ fingerprint.py's machine signal is explicitly documented as detection-only,
4
+ not a security boundary — self-reported by the same process an attacker
5
+ controls. This module obtains a categorically stronger credential: an opaque
6
+ nonce minted by the backend via an authenticated registration call, whose
7
+ hash is what POST /internal/keys/derive actually checks before deriving a
8
+ working KEK.
9
+
10
+ First startup on a deployment: no persisted nonce yet. Calls
11
+ POST /api/projects/{NKX_PROJECT_ID}/runtime-instances, authenticated via
12
+ NKX_REGISTER_TOKEN (a scoped api_token, scopes=['runtime:register']),
13
+ and persists the returned nonce to .nkx/instance_nonce (mode 0600) —
14
+ the same file fingerprint.py's _persisted_nonce() reads.
15
+
16
+ Every subsequent startup reads that file directly and never calls the
17
+ registration endpoint again. A missing/unreadable file (lost volume, fresh
18
+ container without a persistent mount) re-registers, producing a new
19
+ runtime_instances row — the old row is left behind as an orphan, not
20
+ auto-revoked; the backend's stale-aware concurrency cap
21
+ (RUNTIME_INSTANCE_STALE_SECONDS) keeps it from permanently consuming a slot,
22
+ and an admin can revoke it by hand if noticed.
23
+ """
24
+ from __future__ import annotations
25
+ import json
26
+ import os
27
+ import stat
28
+ import urllib.error
29
+ import urllib.request
30
+ from pathlib import Path
31
+
32
+ from .context import (LicenseError, _require_https_origin, _verify_license_jwt,
33
+ credentials_dir)
34
+ from .redact import redact_message
35
+ from .trace import trace
36
+
37
+
38
+ _release_hook_installed = False
39
+
40
+
41
+ class RegistrationDeniedError(LicenseError):
42
+ """The backend explicitly rejected the instance-registration request."""
43
+
44
+
45
+ def _timeout_seconds() -> float:
46
+ raw = os.environ.get("NKX_RUNTIME_TIMEOUT_SECONDS", "").strip()
47
+ if not raw:
48
+ return 10.0
49
+ try:
50
+ return float(raw)
51
+ except ValueError:
52
+ return 10.0
53
+
54
+
55
+ def _post_json(req: urllib.request.Request) -> dict:
56
+ """POST req and parse the JSON response. Deliberately never retried —
57
+ unlike remotekek.py's derive (a pure read, safe to retry), this call
58
+ INSERTs a new runtime_instances row on every success. Retrying after a
59
+ timeout/dropped-connection that the server actually committed would
60
+ silently create a second, orphaned instance row and consume a second
61
+ concurrency-cap slot (caught in review after an earlier version of this
62
+ fix wired the same retrying helper in here as in remotekek.py). Still
63
+ honors NKX_RUNTIME_TIMEOUT_SECONDS — tuning the timeout is safe, only
64
+ retrying an ambiguous-outcome request is not."""
65
+ with urllib.request.urlopen(req, timeout=_timeout_seconds()) as r:
66
+ return json.loads(r.read().decode())
67
+
68
+
69
+ def _nonce_file(repo_root: str | os.PathLike[str]) -> Path:
70
+ """Resolve instance_nonce path — honors NKX_CREDENTIALS_DIR when set.
71
+
72
+ `repo_root` is required, not defaulted. Every function below that can
73
+ reach _register() consumes a licence seat when the file is missing, so
74
+ the one input deciding where we look for it must come from the caller
75
+ that knows which repository is being unlocked — never from the process
76
+ working directory, which is what PKG-02 was. See context.credentials_dir.
77
+ """
78
+ return credentials_dir(repo_root) / "instance_nonce"
79
+
80
+
81
+ def _backend_origin() -> str:
82
+ """NKX_KEK_URL doubles as the backend origin for both the derive call
83
+ (remotekek.py) and this module's registration call — one env var, not
84
+ two, per the plan's customer deploy contract.
85
+ """
86
+ origin = os.environ.get("NKX_KEK_URL", "").strip().rstrip("/")
87
+ if not origin:
88
+ raise LicenseError(
89
+ "NKX_KEK_URL is not set — required to register this runtime "
90
+ "instance with the backend."
91
+ )
92
+ _require_https_origin(origin, env_var="NKX_KEK_URL")
93
+ return origin
94
+
95
+
96
+ def _register(license_jwt: str, *, kind: str = "runtime") -> str:
97
+ """Call POST /api/projects/:id/runtime-instances. Returns the raw nonce.
98
+
99
+ kind is threaded into the request body only on the standard
100
+ (non-session) branch below — a branch-session registration always goes
101
+ through the separate register-instance route, which has its own
102
+ distinguishing FK in the backend's join, so kind doesn't apply there.
103
+ """
104
+ register_token = os.environ.get("NKX_REGISTER_TOKEN", "").strip()
105
+ project_id = os.environ.get("NKX_PROJECT_ID", "").strip()
106
+ if not register_token or not project_id:
107
+ raise LicenseError(
108
+ "NKX_REGISTER_TOKEN and NKX_PROJECT_ID are both required "
109
+ "to self-register a runtime instance."
110
+ )
111
+
112
+ try:
113
+ license_id = _verify_license_jwt(license_jwt)["sub"]
114
+ except LicenseError:
115
+ raise
116
+ except Exception as exc:
117
+ raise LicenseError(f"Cannot register: invalid license key ({exc})") from None
118
+
119
+ # A session_id means this is a branch-session developer registering
120
+ # against POST /projects/:id/sessions/:sid/register-instance, not the
121
+ # standard POST /projects/:id/runtime-instances. Both are built from the
122
+ # same NKX_KEK_URL base — no separate URL env var, matching this
123
+ # module's existing one-env-var contract for the standard path.
124
+ session_id = os.environ.get("NKX_SESSION_ID", "").strip()
125
+ if session_id:
126
+ url = f"{_backend_origin()}/api/projects/{project_id}/sessions/{session_id}/register-instance"
127
+ body = b"{}"
128
+ headers = {
129
+ "x-nkx-register-token": register_token,
130
+ "Content-Type": "application/json",
131
+ }
132
+ else:
133
+ url = f"{_backend_origin()}/api/projects/{project_id}/runtime-instances"
134
+ body = json.dumps({"license_id": license_id, "kind": kind}).encode()
135
+ headers = {
136
+ "x-nkx-api-key": register_token,
137
+ "Content-Type": "application/json",
138
+ }
139
+
140
+ req = urllib.request.Request(url, data=body, method="POST", headers=headers)
141
+ try:
142
+ data = _post_json(req)
143
+ except urllib.error.HTTPError as exc:
144
+ try:
145
+ reason = json.loads(exc.read().decode()).get("error", f"HTTP {exc.code}")
146
+ except Exception:
147
+ reason = f"HTTP {exc.code}"
148
+ # redact_message() before this hits logs/exception text — mirrors
149
+ # remotekek.py's derive_kek()/derive_mock_kek(), which redact their
150
+ # equivalent denial/network-error paths. Without it, a backend error
151
+ # body or proxy that ever echoes request content (register token
152
+ # included) would flow through unredacted here (audit finding B14).
153
+ trace("instanceauth", "register_denied", redact_message(f"Instance registration denied: {reason}"),
154
+ level="error")
155
+ raise RegistrationDeniedError(redact_message(f"Instance registration denied: {reason}")) from None
156
+ except Exception as exc:
157
+ trace("instanceauth", "register_network_error", redact_message(str(exc)), level="error")
158
+ raise LicenseError(redact_message(f"Instance registration request failed: {exc}")) from None
159
+
160
+ nonce = data.get("nonce")
161
+ if not nonce:
162
+ raise LicenseError("Instance registration response missing 'nonce'.")
163
+ trace("instanceauth", "registered", "Runtime instance registered",
164
+ instance_id=(data.get("instance") or {}).get("id"))
165
+ return nonce
166
+
167
+
168
+ def _persist_nonce(nonce: str, repo_root: str | os.PathLike[str]) -> None:
169
+ """Write the nonce with restrictive permissions from the moment the file
170
+ exists — never write-then-chmod. That ordering left a window (and, if
171
+ the chmod step ever failed, potentially forever) where the file sat at
172
+ whatever the process umask happened to allow, typically world-readable
173
+ (audit finding B13). A failure to secure the file is now fatal rather
174
+ than a logged warning — this is a credential, not a cache entry, and a
175
+ process that can't protect it shouldn't silently carry on as if it had.
176
+ """
177
+ nonce_file = _nonce_file(repo_root)
178
+ nonce_file.parent.mkdir(parents=True, exist_ok=True)
179
+ try:
180
+ fd = os.open(str(nonce_file), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
181
+ try:
182
+ os.write(fd, nonce.encode())
183
+ finally:
184
+ os.close(fd)
185
+ # Belt-and-suspenders: force 0600 regardless of umask (some umasks
186
+ # can still widen the mode passed to os.open above).
187
+ os.chmod(nonce_file, stat.S_IRUSR | stat.S_IWUSR)
188
+ except OSError as exc:
189
+ trace("instanceauth", "persist_nonce_failed",
190
+ f"Could not persist instance nonce with restrictive permissions: {exc}",
191
+ level="error")
192
+ raise LicenseError(
193
+ f"Could not persist the instance nonce with restrictive "
194
+ f"permissions ({exc}). Refusing to leave a readable credential "
195
+ f"file on disk."
196
+ ) from None
197
+
198
+
199
+ def existing_instance_nonce(repo_root: str | os.PathLike[str]) -> str | None:
200
+ """This machine's nonce if it already has one, without registering.
201
+
202
+ Spec 16 phase 3 needs the read half on its own: a developer key presents a
203
+ nonce when a change session has put one on disk and presents none
204
+ otherwise, and *registering* one would be exactly the wrong reflex — a
205
+ developer key on mocks has never held a runtime instance, and a seat means
206
+ nothing for generated stub content.
207
+ """
208
+ nonce_path = _nonce_file(repo_root)
209
+ if not nonce_path.exists():
210
+ return None
211
+ try:
212
+ nonce = nonce_path.read_text().strip()
213
+ except OSError:
214
+ return None
215
+ return nonce or None
216
+
217
+
218
+ def ensure_instance_nonce(license_jwt: str, repo_root: str | os.PathLike[str]) -> str:
219
+ """Return this deployment's registered instance nonce, registering with
220
+ the backend on first startup. Raises LicenseError on failure — callers
221
+ (loader.py) treat that as fail-closed at startup, same as a failed derive.
222
+ Always registers kind='runtime' (the default) — this is the persisted,
223
+ long-running-deployment path; see register_ci_instance() for the
224
+ ephemeral CI counterpart.
225
+ """
226
+ nonce = existing_instance_nonce(repo_root)
227
+ if nonce:
228
+ return nonce
229
+ nonce = _register(license_jwt)
230
+ _persist_nonce(nonce, repo_root)
231
+ return nonce
232
+
233
+
234
+ def release_on_shutdown(license_jwt: str, repo_root: str | os.PathLike[str]) -> None:
235
+ """Arrange for this deployment's seat to be handed back when it stops.
236
+
237
+ Two hooks, because one is not enough and the other is not always ours to
238
+ install:
239
+
240
+ `atexit` covers a normal interpreter exit — a worker finishing, an
241
+ unhandled exception unwinding, `sys.exit()`, and a KeyboardInterrupt, since
242
+ that raises rather than killing.
243
+
244
+ `atexit` does **not** run on SIGTERM, and SIGTERM is precisely what an
245
+ orchestrator sends the outgoing container of a rolling deploy: the exact
246
+ case this whole fix exists for. So SIGTERM is handled too — but only if the
247
+ process has not already installed its own handler. A library that quietly
248
+ replaces an application's signal handling breaks shutdown in ways that are
249
+ very hard to trace back, so a host app that has said what SIGTERM means
250
+ keeps its answer, and gets the atexit path if its own handler exits
251
+ normally. Whatever was there before is chained rather than dropped.
252
+
253
+ Registered once per process. Never raises: this is called during a
254
+ successful startup, and failing to arrange a courtesy at shutdown must not
255
+ stop a deployment from starting.
256
+ """
257
+ global _release_hook_installed
258
+ if _release_hook_installed:
259
+ return
260
+ _release_hook_installed = True
261
+
262
+ try:
263
+ import atexit
264
+ import signal
265
+
266
+ atexit.register(lambda: release_instance(license_jwt, repo_root))
267
+
268
+ previous = signal.getsignal(signal.SIGTERM)
269
+ # SIG_DFL means nothing has claimed it. Anything else is the host
270
+ # application's decision and is left alone.
271
+ if previous is signal.SIG_DFL:
272
+ def _on_sigterm(signum, frame): # noqa: ANN001 - signal handler signature
273
+ release_instance(license_jwt, repo_root)
274
+ # Restore and re-raise so the process dies exactly as it would
275
+ # have: same signal, same exit status, no swallowed shutdown.
276
+ signal.signal(signal.SIGTERM, signal.SIG_DFL)
277
+ os.kill(os.getpid(), signal.SIGTERM)
278
+
279
+ signal.signal(signal.SIGTERM, _on_sigterm)
280
+ except Exception as exc:
281
+ # Includes ValueError from signal.signal() off the main thread, which
282
+ # is normal in a worker and simply means atexit carries this alone.
283
+ trace("instanceauth", "release_hook_failed",
284
+ f"Could not install the seat-release hook (non-fatal): {exc}", level="warn")
285
+
286
+
287
+ def release_instance(license_jwt: str, repo_root: str | os.PathLike[str]) -> bool:
288
+ """Hand this deployment's licence seat back on the way out.
289
+
290
+ A seat used to come back one of two ways: a steward revoking the row by
291
+ hand, or the backend ageing `last_seen` past its staleness window, which is
292
+ fifteen hours. Neither describes a container. A replacement replica starts
293
+ with an empty filesystem, so it registers as a new identity and takes a new
294
+ seat while the one it replaced keeps its own for the rest of that window
295
+ with nothing running behind it. On containers that is every deploy, and a
296
+ twenty-seat licence fills up in about two days of ordinary rolling
297
+ releases. This is the process saying "I am done" so the seat is free now
298
+ rather than tomorrow.
299
+
300
+ Never raises, and never blocks shutdown. Every failure here — no nonce, no
301
+ project id, an unreachable backend, a slow one — leaves exactly the
302
+ behaviour that existed before this function did: the seat ages out on the
303
+ server's own timer. Turning a clean exit into a traceback, or into a
304
+ process that hangs on a dead endpoint while an orchestrator waits to kill
305
+ it, would be a far worse bug than the one this fixes.
306
+
307
+ It does, however, **say** so. Never-raise is not never-report, and
308
+ conflating the two is what let the first version of this fail in every real
309
+ deployment without emitting a single line.
310
+
311
+ Returns True only when the backend confirmed the release, so callers can
312
+ trace it; nothing depends on the value.
313
+ """
314
+ # Every "cannot release" below traces at warn. The first version of this
315
+ # returned False in silence, on the reasoning that shutdown must never be
316
+ # noisy — and that reasoning hid a total failure: NKX_REGISTER_TOKEN, which
317
+ # it then required, is zeroized by client.install()'s `finally` the moment
318
+ # install completes (audit B22). So in a real deployment the token was
319
+ # always gone by exit, the release always short-circuited here, and with
320
+ # NKX_TRACE=1 a clean boot emitted `registered` and then nothing at all.
321
+ # Silence is fine for a failure that is visible some other way. It is not
322
+ # fine for the only signal a dead path has.
323
+ nonce = existing_instance_nonce(repo_root)
324
+ if not nonce:
325
+ trace("instanceauth", "release_skipped",
326
+ "no instance nonce on disk — nothing to release", level="warn")
327
+ return False
328
+
329
+ project_id = os.environ.get("NKX_PROJECT_ID", "").strip()
330
+ if not project_id:
331
+ trace("instanceauth", "release_skipped",
332
+ "NKX_PROJECT_ID is unset — cannot address the release endpoint",
333
+ level="warn")
334
+ return False
335
+
336
+ try:
337
+ license_id = _verify_license_jwt(license_jwt)["sub"]
338
+ url = f"{_backend_origin()}/api/projects/{project_id}/runtime-instances/release"
339
+ body = json.dumps({"license_id": license_id, "instance_nonce": nonce}).encode()
340
+ # The licence JWT, not NKX_REGISTER_TOKEN. Registering happens at
341
+ # startup, when the register token is still live; releasing happens at
342
+ # shutdown, when B22 has deliberately destroyed it. The licence key and
343
+ # the nonce are both still held, because derive needs them every
344
+ # refresh, so authenticating with those costs no new long-lived secret
345
+ # and leaves the zeroize intact.
346
+ req = urllib.request.Request(
347
+ url, data=body, method="POST",
348
+ headers={"Authorization": f"Bearer {license_jwt}",
349
+ "Content-Type": "application/json"},
350
+ )
351
+ # Deliberately shorter than _timeout_seconds(): this runs while the
352
+ # process is already shutting down, and an orchestrator's grace period
353
+ # is typically ten seconds before it escalates to SIGKILL. Better to
354
+ # give up on the release than to be killed mid-shutdown.
355
+ with urllib.request.urlopen(req, timeout=3) as resp:
356
+ json.loads(resp.read().decode())
357
+ trace("instanceauth", "released", "Runtime instance seat released on shutdown")
358
+ return True
359
+ except Exception as exc:
360
+ # redact_message for the same reason _register does: an error body or
361
+ # a proxy that echoes request content would otherwise carry the
362
+ # register token into logs (audit B14).
363
+ trace("instanceauth", "release_failed",
364
+ redact_message(f"Could not release the instance seat (non-fatal): {exc}"),
365
+ level="warn")
366
+ return False
367
+
368
+
369
+ def register_ci_instance(license_jwt: str) -> str:
370
+ """Register a one-shot kind='ci_materialize' instance for a CI build —
371
+ used by materialize.py's license_jwt= path (core/src/nkx/materialize.py)
372
+ ahead of the caller's own compiler run.
373
+
374
+ Deliberately bypasses ensure_instance_nonce()'s persisted-file read/reuse:
375
+ a CI container has nothing durable to persist an instance_nonce file to,
376
+ and reusing a stale nonce across unrelated builds would be wrong anyway.
377
+ Every call registers a fresh instance; the backend never counts these
378
+ rows toward a license's max_concurrent_instances (see
379
+ backend/src/lib/runtimeInstances.ts's countActiveRuntimeInstances), so
380
+ CI churn never contends with real deployment seats. Nothing is persisted
381
+ to disk and nothing is ever revoked here — the row is left behind as an
382
+ intentional orphan (see backend/CONTEXT.md's Known Gaps).
383
+ """
384
+ return _register(license_jwt, kind="ci_materialize")