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,470 @@
1
+ """Stage 3: build-time decryption.
2
+
3
+ An import hook decrypts protected modules in memory. The KEK for a running
4
+ customer process is no longer derived locally from NKX_KEY — it's
5
+ obtained from the backend via the registered-instance exchange (Part 2 of
6
+ the registered-instance KEK plan; see instanceauth.py, remotekek.py).
7
+ nkx_key never leaves the backend and is never present in this process's
8
+ environment. Plaintext never returns to disk.
9
+
10
+ _build_kek (below) still exists and still does local scrypt→HKDF derivation
11
+ from a passphrase — but it's now only used by protect.py/materialize.py and
12
+ the CLI's unlock/reseal/rekey commands, which run as backend-controlled,
13
+ one-shot job containers that receive the master key directly via --key.
14
+ That path is explicitly out of scope for this exchange (see remotekek.py's
15
+ module docstring); only the long-running ProtectedFinder import-hook path
16
+ changed.
17
+
18
+ v2 manifest, remote-derive path: license JWT + registered instance nonce +
19
+ build_id → POST /internal/keys/derive → KEK → unwrap DEK → decrypt.
20
+
21
+ v1 manifests, and any v2 manifest missing context.build_id, are rejected at
22
+ ProtectedFinder init — re-protect to upgrade.
23
+
24
+ If the KEK is wrong (revoked instance, stale cache after a denied refresh),
25
+ DEK unwrapping fails with an InvalidTag exception, re-raised as ImportError
26
+ with a diagnostic.
27
+ """
28
+ import base64
29
+ import functools
30
+ import importlib.abc
31
+ import importlib.util
32
+ import json
33
+ import os
34
+ import sys
35
+ from pathlib import Path
36
+
37
+ from .crypto import BLOB_EXT, bind_context_kek, decrypt_blob, derive_kek, slot_aad, unwrap_dek, zeroize
38
+ from .manifest import binding_name, version_error
39
+
40
+
41
+ def _build_kek(manifest: dict, key: str) -> bytes:
42
+ """Derive the final KEK from the passphrase and (for v2) runtime context."""
43
+ base_kek = derive_kek(key, manifest["kdf"])
44
+ if manifest.get("version", 1) < 2 or "context" not in manifest:
45
+ return base_kek
46
+
47
+ from . import context as C
48
+ ctx = manifest["context"]
49
+ sources = ctx.get("runtime_sources") or []
50
+ runtime_values = C.collect(sources)
51
+ info = C.assemble_info(
52
+ ctx.get("build_id", ""),
53
+ ctx.get("tenant_id", ""),
54
+ runtime_values,
55
+ customer_id=ctx.get("customer_id", ""),
56
+ )
57
+ return bind_context_kek(base_kek, info)
58
+
59
+
60
+ def _context_diagnostic(manifest: dict) -> str:
61
+ """Human-readable summary of what context factors were required."""
62
+ ctx = manifest.get("context")
63
+ if not ctx:
64
+ return "no context binding (v1 manifest)"
65
+ parts = []
66
+ if ctx.get("build_id"):
67
+ parts.append(f"build_id={ctx['build_id']!r}")
68
+ if ctx.get("tenant_id"):
69
+ parts.append(f"tenant_id={ctx['tenant_id']!r}")
70
+ sources = ctx.get("runtime_sources") or []
71
+ if sources:
72
+ parts.append(f"runtime_sources={sources}")
73
+ return "required context: " + (", ".join(parts) or "(none)")
74
+
75
+
76
+ class _Loader(importlib.abc.Loader):
77
+ def __init__(self, finder: "ProtectedFinder", fullname: str):
78
+ self.finder = finder
79
+ self.fullname = fullname
80
+
81
+ def create_module(self, spec):
82
+ return None
83
+
84
+ def exec_module(self, module):
85
+ rel, entry = self.finder.modules[self.fullname]
86
+ blob = (self.finder.root / (rel + BLOB_EXT)).read_bytes()
87
+ # A fresh, mutable copy from the manager (audit finding B12) — scrub
88
+ # it the moment it's no longer needed instead of leaving it to sit
89
+ # in memory until GC (which wouldn't scrub it anyway; bytes can't be).
90
+ kek = self.finder.kek
91
+ # The repo-relative name, which is what the ciphertext was sealed
92
+ # under — `rel` is short of it by the package root in a per-root view.
93
+ name = binding_name(self.finder.manifest, rel)
94
+ try:
95
+ dek = unwrap_dek(base64.b64decode(entry["wrapped_dek"]), kek, slot_aad(name, "dek"))
96
+ except Exception:
97
+ diag = _context_diagnostic(self.finder.manifest)
98
+ raise ImportError(
99
+ f"nkx: cannot decrypt {self.fullname!r} — "
100
+ f"stale or revoked KEK.\n"
101
+ f" {diag}\n"
102
+ f" Check that NKX_KEK_URL is reachable and that this "
103
+ f"instance and license are still active."
104
+ ) from None
105
+ finally:
106
+ zeroize(kek)
107
+ source = decrypt_blob(blob, dek, slot_aad(name, "content")) # plaintext exists only in memory
108
+ code = compile(source, rel, "exec")
109
+ exec(code, module.__dict__)
110
+
111
+
112
+ def _hook_modules(manifest: dict) -> dict:
113
+ """Only "hook" entries have a Python-importable module id at all —
114
+ "prebuild"/"hook-bytecode" entries are decrypted by `materialize` or a
115
+ language-specific bytecode loader, never via sys.meta_path."""
116
+ return {
117
+ e["module"]: (rel, e)
118
+ for rel, e in manifest["files"].items()
119
+ if e.get("load_strategy", "hook") == "hook" and "module" in e
120
+ }
121
+
122
+
123
+ class ProtectedFinder(importlib.abc.MetaPathFinder):
124
+ def __init__(self, root: str, manifest: dict, kek_manager=None):
125
+ """`kek_manager` lets the caller hand over a manager it already built.
126
+
127
+ Spec 16 phase 3: _install_core does the derive itself, because the
128
+ *server's* answer is what decides whether this finder or DevModeFinder
129
+ gets installed. Deriving here as well would mean two round trips and,
130
+ worse, two chances for the two calls to disagree.
131
+
132
+ Passing None makes this build its own manager, and that is not a
133
+ second live derive path. _install_core reaches it only in its
134
+ fallback, where it exists to raise: with no token on disk, "no license
135
+ key found"; with a runtime key and no NKX_KEK_URL, the
136
+ backend-unreachable error the developer branch defers to on purpose.
137
+ Constructing the finder is what picks between the two messages. Tests
138
+ call it directly; materialize.py does not — it imports _build_kek and
139
+ never builds a finder at all.
140
+ """
141
+ self.root = Path(root)
142
+ self.manifest = manifest
143
+ problem = version_error(manifest)
144
+ if problem is not None:
145
+ raise ImportError(problem)
146
+
147
+ from . import context as C
148
+ from . import instanceauth
149
+ from . import remotekek
150
+
151
+ if kek_manager is not None:
152
+ self._kek_manager = kek_manager
153
+ self.modules = _hook_modules(manifest)
154
+ return
155
+
156
+ token = C._read_license_token()
157
+ if not token:
158
+ raise ImportError(
159
+ "nkx: No license key found. Set NKX_LICENSE_KEY or "
160
+ "place it in .nkx/license.key."
161
+ )
162
+ try:
163
+ # build_id_from_manifest() raises LicenseError same as everything
164
+ # else below — kept inside this try (not called ahead of it) so a
165
+ # manifest missing context.build_id gets the same ImportError
166
+ # conversion/redaction/cause-chain treatment as every other
167
+ # license failure here, instead of escaping as a raw LicenseError
168
+ # (audit finding B23).
169
+ build_id = remotekek.build_id_from_manifest(manifest)
170
+ # Offline signature + expiry check only — deliberately NOT
171
+ # context.check_license()/_check_revocation_online(). Revocation
172
+ # is enforced by the derive call itself (below), which collapses
173
+ # the old two-round-trip startup (validate + real work) into one.
174
+ C._verify_license_jwt(token)
175
+ instance_nonce = instanceauth.ensure_instance_nonce(token, root)
176
+ # Hand the seat back when this process stops, rather than leaving
177
+ # the backend to age it out fifteen hours later. A replaced
178
+ # container is a new identity holding a new seat, so without this
179
+ # every deploy leaks one.
180
+ instanceauth.release_on_shutdown(token, root)
181
+ # want="real": this finder only ever serves real content, so a
182
+ # backend that would answer "mock" must deny instead of quietly
183
+ # handing back a KEK that unwraps nothing here.
184
+ derive_fn = functools.partial(remotekek.derive_kek, token, instance_nonce, build_id, "real",
185
+ repo_root=root)
186
+ self._kek_manager = remotekek.RemoteKekManager(derive_fn)
187
+ except C.LicenseError as exc:
188
+ # `from exc` (not `from None`) deliberately keeps the original
189
+ # typed exception as __cause__ — nkx_runtime.client uses it to
190
+ # re-raise the matching public error class (audit finding B21).
191
+ raise ImportError(f"nkx: {exc}") from exc
192
+ self._kek_manager.start_refresh_thread()
193
+ self.modules = _hook_modules(manifest)
194
+
195
+ @property
196
+ def kek(self) -> bytearray:
197
+ return self._kek_manager.current_kek()
198
+
199
+ def find_spec(self, fullname, path, target=None):
200
+ if fullname in self.modules:
201
+ return importlib.util.spec_from_loader(
202
+ fullname, _Loader(self, fullname)
203
+ )
204
+ return None
205
+
206
+
207
+ def _derive_for_install(root: str, manifest: dict):
208
+ """One derive call, and the server's answer about what it unlocks.
209
+
210
+ Returns (manager, content) or None when this machine cannot ask — no
211
+ licence key on disk, in which case the caller falls through to
212
+ ProtectedFinder's own error, which says so in the terms a customer
213
+ understands.
214
+
215
+ The nonce is presented when this machine already has one, and registered
216
+ only for a runtime key. A developer key on mocks has never registered a
217
+ runtime instance and must not start now: registration consumes a seat, and
218
+ a seat means nothing for generated stub content. Reading `kind` off the
219
+ token to decide that is not the client deciding its own routing — it is
220
+ the client deciding whether it has anything to register.
221
+ """
222
+ from . import context as C
223
+ from . import instanceauth
224
+ from . import remotekek
225
+
226
+ token = C._read_license_token()
227
+ if not token:
228
+ return None
229
+
230
+ try:
231
+ build_id = remotekek.build_id_from_manifest(manifest)
232
+ payload = C._verify_license_jwt(token)
233
+ # `kind` since spec 16 phase 2; `purpose` is the older spelling and
234
+ # still what a token issued before that carries.
235
+ is_developer = (payload.get("kind") or payload.get("purpose")) == "developer"
236
+
237
+ nonce = instanceauth.existing_instance_nonce(root)
238
+ if nonce is None and not is_developer:
239
+ nonce = instanceauth.ensure_instance_nonce(token, root)
240
+ # Only a runtime key holds a seat — a developer key on mocks never
241
+ # registered one, so there is nothing for it to give back.
242
+ if nonce is not None and not is_developer:
243
+ instanceauth.release_on_shutdown(token, root)
244
+
245
+ # want="any": this is startup, and the process has no content yet to
246
+ # be downgraded from. It asks what it is entitled to and installs the
247
+ # matching finder. Every *later* call from the manager asks for what
248
+ # it is already running, which is what turns a withdrawal into an
249
+ # explicit denial rather than a silent switch.
250
+ derive_fn = functools.partial(remotekek.derive_kek, token, nonce, build_id, "any",
251
+ repo_root=root)
252
+ manager = remotekek.RemoteKekManager(derive_fn)
253
+ except C.LicenseError as exc:
254
+ # `from exc` (not `from None`) deliberately keeps the original typed
255
+ # exception as __cause__ — nkx_runtime.client uses it to re-raise the
256
+ # matching public error class (audit finding B21).
257
+ raise ImportError(f"nkx: {exc}") from exc
258
+
259
+ content = manager.result.content
260
+ # Every refresh from here on states what this process is actually running,
261
+ # so withdrawing it is a denial the manager can act on rather than a
262
+ # different answer it would have to interpret.
263
+ manager.set_derive_fn(functools.partial(
264
+ remotekek.derive_kek, token, nonce, build_id, content
265
+ ))
266
+ manager.start_refresh_thread()
267
+ return manager, content
268
+
269
+
270
+ def _announce_real_content(manager) -> None:
271
+ """Say — unmissably, on stderr — that this process is decrypting real code.
272
+
273
+ Decision B: elevation gives real code in memory, not only on disk. That is
274
+ a genuinely different thing to be running, and the one property it must
275
+ have is that nobody is surprised by it: a developer who thinks they are
276
+ testing against stubs must not quietly be running the crown jewels, and a
277
+ steward reading a terminal over someone's shoulder should be able to tell.
278
+ The backend logs the same fact against the session.
279
+ """
280
+ session_id = manager.result.session_id
281
+ if not session_id:
282
+ # An ordinary deployment running real code is not news.
283
+ return
284
+ until = manager.result.session_expires_at or "the session is closed"
285
+ print(
286
+ "\n"
287
+ " ┌───────────────────────────────────────────────────────────────┐\n"
288
+ " │ REAL PROTECTED CODE IS BEING DECRYPTED IN THIS PROCESS │\n"
289
+ " └───────────────────────────────────────────────────────────────┘\n"
290
+ f" change session : {session_id}\n"
291
+ f" until : {until}\n"
292
+ " This is not mock content. Closing the session stops this process.\n",
293
+ file=sys.stderr, flush=True,
294
+ )
295
+
296
+
297
+ def _announce_unelevated_session() -> None:
298
+ """Say why a process that expected real code is running stubs.
299
+
300
+ Setting NKX_SESSION_ID is a developer stating an expectation. If this
301
+ machine has never registered a nonce against that session it is not
302
+ elevated, the server answers `mock`, and — because startup asks `any`,
303
+ having no content yet to be downgraded from — that answer is correct and
304
+ silent. Silent is the problem: a developer who believes they are testing
305
+ against the real thing and is not is the exact failure `want` exists to
306
+ prevent, and here it is the one case `want` cannot catch.
307
+
308
+ Nothing is wrong with the process; it just is not what was asked for. So
309
+ this is a notice, not an error, and it says what to do about it.
310
+ """
311
+ if not os.environ.get("NKX_SESSION_ID", "").strip():
312
+ return
313
+ print(
314
+ "\nnkx: NKX_SESSION_ID is set, but this process is running MOCK content.\n"
315
+ "nkx: this machine is not registered against that change session, so it\n"
316
+ "nkx: is not elevated. Run an nkx-dev command here to register it, then\n"
317
+ "nkx: restart — or ask a steward whether the session is still open.\n",
318
+ file=sys.stderr, flush=True,
319
+ )
320
+
321
+
322
+ # Roots this process has already installed a finder for. Keyed by root rather
323
+ # than a single process-wide flag: a monorepo mounts one package root per
324
+ # service (manifest.py's per-root views), and a flat flag would silently refuse
325
+ # the second root instead of the second *install of the same root*, which is
326
+ # the actual defect. Python tolerates several finders on sys.meta_path — it is
327
+ # a list, not a monkeypatch chain — so one per root is correct and one per call
328
+ # is not.
329
+ _installed_roots: set[str] = set()
330
+
331
+
332
+ def _install_finder(root: str, finder) -> None:
333
+ """Insert the import hook, and latch this root against a second install.
334
+
335
+ Latched here rather than on entry to _install_core() so that a repo with no
336
+ manifest, or a failed derive, leaves a later call free to try again — but
337
+ once a finder is on sys.meta_path for a root, a second one is never added.
338
+
339
+ A service whose entrypoint calls RuntimeClient.install() while also being
340
+ launched under nkx-run did exactly that: a second finder, a second
341
+ RemoteKekManager, a second derive on every refresh interval, and two KEK
342
+ buffers held for the life of the process (PKG-10). There is no uninstall to
343
+ pair with this; the hook is meant to live as long as the process.
344
+ """
345
+ _installed_roots.add(str(Path(root).resolve()))
346
+ sys.meta_path.insert(0, finder)
347
+
348
+
349
+ def _install_core(root: str = ".") -> None:
350
+ """Install the ProtectedFinder import hook (or dev-mode stub).
351
+
352
+ Internal entry point — ``nkx_runtime.RuntimeClient.install()`` calls
353
+ this directly so it never re-enters the deprecated ``install()`` wrapper
354
+ (which would recurse when nkx-runtime is installed).
355
+ """
356
+ if str(Path(root).resolve()) in _installed_roots:
357
+ return
358
+ manifest_path = Path(root) / ".nkx" / "manifest.json"
359
+ if not manifest_path.exists():
360
+ return
361
+ manifest = json.loads(manifest_path.read_text())
362
+
363
+ from . import context as C
364
+
365
+ dev_mode = os.environ.get("NKX_DEVMODE") == "1"
366
+ has_backend = bool(os.environ.get("NKX_KEK_URL", "").strip())
367
+
368
+ # build_id lives under manifest["context"], but kdf/key_version are
369
+ # top-level manifest fields — easy to get wrong wiring this, since
370
+ # build_id sits at a different nesting level than the other two.
371
+ # license_jwt is read the same raw way check_license() does — a bare
372
+ # lookup, not a verification; DevModeFinder only needs it lazily, on
373
+ # the first import of a file that actually has wrapped_mock_dek.
374
+ devmode_ctx = manifest.get("context") or {}
375
+ devmode_kwargs = {
376
+ "build_id": devmode_ctx.get("build_id", ""),
377
+ "kdf": manifest.get("kdf"),
378
+ "key_version": manifest.get("key_version"),
379
+ "license_jwt": C._read_license_token(),
380
+ }
381
+
382
+ if dev_mode and not has_backend:
383
+ # No NKX_KEK_URL means there's no way to reach the backend for a
384
+ # real KEK anyway. Legacy plaintext stubs are loaded from .mock.py
385
+ # files — they never touch the KEK, so DevMode works on both v1 and
386
+ # v2 manifests. A file with wrapped_mock_dek still requires a
387
+ # reachable NKX_KEK_URL to decrypt — with none configured, that
388
+ # import fails with DevModeFinder's own distinct error, not
389
+ # silently falling back to a stale/missing plaintext copy. If
390
+ # NKX_KEK_URL *is* set, dev_mode alone doesn't force stubs — a
391
+ # real backend is reachable, so fall through to the real decrypt
392
+ # path (mirrors the old "a real key overrides devmode" escape hatch).
393
+ # That fall-through is reachable from `nkx run` only: nkx-runtime
394
+ # refuses the combination earlier, in credentials/chain.py, so a
395
+ # customer deployment never arrives here with both set.
396
+ from .devmode import DevModeFinder
397
+ _install_finder(root, DevModeFinder(root, manifest, **devmode_kwargs))
398
+ return
399
+
400
+ if not has_backend and C.is_developer_license():
401
+ # No NKX_KEK_URL, so there is no server to make the routing decision
402
+ # and no way to derive anything. Offline, a developer key has exactly
403
+ # two possible outcomes — legacy plaintext stubs, or a loud failure on
404
+ # the first import of a file that needs a KEK — and DevModeFinder
405
+ # produces both correctly. Choosing between them here is not the
406
+ # client granting itself anything: real content is unreachable either
407
+ # way, and this path can only ever serve *less*. A runtime key falls
408
+ # through to ProtectedFinder, whose error says plainly that the
409
+ # backend is unreachable, which is the right answer for a deployment.
410
+ try:
411
+ payload = C.check_license()
412
+ except C.LicenseError as exc:
413
+ raise ImportError(f"nkx: {exc}") from exc
414
+ C.start_heartbeat_thread(payload)
415
+ from .devmode import DevModeFinder
416
+ _install_finder(root, DevModeFinder(root, manifest, **devmode_kwargs))
417
+ return
418
+
419
+ if has_backend:
420
+ # ── The routing decision, and where it is made ──────────────────────
421
+ #
422
+ # This used to be `if C.is_developer_license(): serve mocks` — decided
423
+ # here, on the developer's own machine, from a claim in the developer's
424
+ # own token, before any network call. It was not wrong about what a
425
+ # developer should get, but it made the party the decision constrains
426
+ # the party making it, and it left `nkx-dev unlock` writing plaintext
427
+ # to disk as the only way a developer could ever reach real code.
428
+ #
429
+ # Spec 16 phase 3 asks the server instead (platform invariant 2: key
430
+ # derivation is server-authoritative — including the routing). One
431
+ # derive call answers both "may you" and "what do you get", and this
432
+ # function installs whichever finder the answer names.
433
+ derived = _derive_for_install(root, manifest)
434
+ if derived is not None:
435
+ manager, content = derived
436
+ if content == "real":
437
+ _announce_real_content(manager)
438
+ _install_finder(root, ProtectedFinder(root, manifest, kek_manager=manager))
439
+ else:
440
+ _announce_unelevated_session()
441
+ from .devmode import DevModeFinder
442
+ _install_finder(root, DevModeFinder(root, manifest, kek_manager=manager, **devmode_kwargs))
443
+ return
444
+
445
+ # Reached only to raise, and with two different messages deliberately: no
446
+ # token gives "no license key found", a runtime key with no NKX_KEK_URL
447
+ # gives the backend-unreachable error the developer branch above defers to.
448
+ # Constructing the finder is what picks between them.
449
+ finder = ProtectedFinder(root, manifest)
450
+ _install_finder(root, finder)
451
+
452
+
453
+ def install(root: str = ".") -> None:
454
+ import warnings
455
+
456
+ warnings.warn(
457
+ "nkx.install() is deprecated; use "
458
+ "nkx_runtime.RuntimeClient.from_env().install() instead.",
459
+ DeprecationWarning,
460
+ stacklevel=2,
461
+ )
462
+ try:
463
+ from nkx_runtime import RuntimeClient
464
+
465
+ RuntimeClient.from_env(repo_root=root).install(repo_root=root)
466
+ return
467
+ except ImportError:
468
+ pass
469
+
470
+ _install_core(root)