nkx-runtime 2.2.0__py3-none-any.whl

nkx_runtime/__init__.py

@@ -0,0 +1,41 @@
+"""Nakodax customer runtime SDK."""
+
+from .client import RuntimeClient
+from .config import RuntimeConfig
+from .errors import (
+    ConfigurationError,
+    KekDeniedError,
+    KekUnreachableError,
+    NkxError,
+    RegistrationDeniedError,
+)
+
+__all__ = [
+    "RuntimeClient",
+    "RuntimeConfig",
+    "NkxError",
+    "ConfigurationError",
+    "KekDeniedError",
+    "KekUnreachableError",
+    "RegistrationDeniedError",
+    "__version__",
+]
+
+
+def _installed_version() -> str:
+    """The installed distribution's version, not a constant.
+
+    The hardcoded string sat at 1.0.0 while the package shipped 2.1.1, because
+    the CI version gate compares the tag against pyproject.toml and
+    package.json only and never looked here (PKG-08). Reading the installed
+    distribution means there is no second place to update, and a repacked
+    wheel reports honestly. Mirrors cli.py's _version().
+    """
+    try:
+        from importlib.metadata import version
+        return version("nkx-runtime")
+    except Exception:
+        return "unknown"
+
+
+__version__ = _installed_version()

nkx_runtime/_core/__init__.py

@@ -0,0 +1 @@
+"""Synced runtime engine (private); do not edit — run make sync-sdk-python-runtime."""

nkx_runtime/_core/context.py

@@ -0,0 +1,628 @@
+"""Runtime context collection and HKDF info assembly for multi-factor KEK binding.
+
+Each "source" is a named collector that returns a stable string for the current
+environment. The assembled info bytes are fed into HKDF as the non-secret but
+binding `info` parameter — a different environment produces a different KEK, so
+a copied artifact cannot be decrypted outside the environment it was bound to.
+
+Available sources
+-----------------
+machine_id       Per-machine OS identifier (/etc/machine-id on Linux,
+                 IOPlatformUUID on macOS). Binds the artifact to one machine.
+env_token        NKX_RUNTIME_TOKEN env var. Operator-injected secret (Vault
+                 lease, KMS-derived token, per-seat license key). The token is
+                 the runtime "factor" — without it the KEK is wrong.
+aws_instance_id  EC2 instance ID from IMDS. Binds to one EC2 instance.
+gcp_instance_id  GCP instance ID from metadata server. Binds to one GCP VM.
+license_key      RS256-signed JWT from NKX_LICENSE_KEY env var (or
+                 .nkx/license.key). Verifies signature + expiry offline;
+                 optionally checks revocation via NKX_VALIDATE_URL.
+                 At protect time, NKX_LICENSE_UUID bypasses JWT verification
+                 so the vendor container can bind the UUID without the signed key.
+                 The stable license UUID (JWT sub claim) is the HKDF input.
+"""
+from __future__ import annotations
+import base64
+import hashlib
+import json
+import os
+import platform
+import subprocess
+import time
+from pathlib import Path
+
+from .trace import trace
+
+
+# ── LicenseError ──────────────────────────────────────────────────────────────
+
+class LicenseError(Exception):
+    """Raised when a license check fails (invalid, expired, or revoked)."""
+
+
+# ── Backend origin scheme enforcement (audit finding B17) ───────────────────
+# NKX_KEK_URL carries the license JWT bearer token, the runtime token, the
+# register token, and the derived KEK itself. Accepting a plain http:// origin
+# would send all of those in cleartext with no other signal that a downgrade
+# happened. NKX_ALLOW_INSECURE_BACKEND_URL is the explicit, documented escape
+# hatch for local dev/test against a plaintext backend.
+
+def _require_https_origin(origin: str, *, env_var: str) -> None:
+    if origin.lower().startswith("https://"):
+        return
+    if os.environ.get("NKX_ALLOW_INSECURE_BACKEND_URL", "").strip().lower() in ("1", "true"):
+        trace("context", "insecure_backend_url_allowed",
+              f"{env_var}={origin!r} is not https:// — allowed via NKX_ALLOW_INSECURE_BACKEND_URL",
+              level="warn")
+        return
+    raise LicenseError(
+        f"{env_var} must be an https:// URL (got {origin!r}) — it carries the "
+        "license token, runtime token, and derived KEK in cleartext otherwise. "
+        "Set NKX_ALLOW_INSECURE_BACKEND_URL=1 to explicitly allow http:// "
+        "(local dev/test only)."
+    )
+
+
+# ── License public key (RS256) ────────────────────────────────────────────────
+# This key is used for offline JWT signature verification.
+# The matching private key lives only in the Nakodax backend.
+# Set at runtime with the NKX_LICENSE_PUBLIC_KEY env var — no embedded default
+# (removed — audit finding A5/B90/#1: a keypair shared across every deployment
+# lets anyone who has it forge a signature offline-verified as genuine, and a
+# *silent* fallback meant a broken secret-injection step failed open instead
+# of loud, which is what B20 partially addressed by tracing it — the actual
+# fix is not falling back at all).
+
+
+def _get_public_key() -> str:
+    configured = os.environ.get("NKX_LICENSE_PUBLIC_KEY", "").strip()
+    if not configured:
+        raise LicenseError(
+            "NKX_LICENSE_PUBLIC_KEY is not set — there is no default public key "
+            "any more. Set it to the public half of the keypair the issuing "
+            "Nakodax backend signs licenses with."
+        )
+    return configured.replace("\\n", "\n")
+
+
+def _b64url_decode(s: str) -> bytes:
+    s += "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s)
+
+
+# Both sides of the expiry comparison are already UTC and carry no timezone:
+# the backend mints `exp` as `Math.floor(expiresAt.getTime() / 1000)` (epoch
+# seconds) and `time.time()` returns epoch seconds. So there is nothing to
+# convert here, and a timezone is not what goes wrong. What goes wrong is the
+# host clock being *wrong* — a container or a box with no NTP drifting ahead —
+# which no amount of timezone handling can fix, because the instant itself is
+# misread.
+#
+# A fast clock rejects a licence the control plane would have accepted, and the
+# app does not start at all. This check is deliberately offline and runs before
+# any network call (see loader.py), so the authoritative answer is not available
+# to contradict it. Hence the leeway: small on purpose, because it cuts the
+# other way too — it also extends a genuinely expired licence by the same
+# margin. A minute absorbs ordinary drift without meaningfully prolonging a dead
+# key.
+CLOCK_SKEW_LEEWAY_SECONDS = 60
+
+
+def _fmt_utc(epoch_seconds: float) -> str:
+    return time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime(epoch_seconds))
+
+
+def _expiry_error(exp: float) -> str:
+    """The message a customer sees when the offline expiry check fails.
+
+    It names both causes, because this code cannot tell them apart: the licence
+    really has expired, or this machine's clock is ahead. The previous wording
+    asserted only the first ("Contact your vendor to renew"), which sent
+    customers to the vendor for a problem the vendor cannot see and cannot fix
+    — the licence reads as valid on the control plane, because it is.
+
+    Both timestamps are rendered in UTC, not local time. A customer comparing
+    two local-time strings across a timezone would see a plausible-looking gap
+    that is not the problem, and chase it.
+    """
+    now = time.time()
+    return (
+        f"License key expired at {_fmt_utc(exp)}, and this machine's clock "
+        f"reads {_fmt_utc(now)}.\n"
+        f"Either the license needs renewing (contact your vendor), or this "
+        f"machine's clock is wrong.\n"
+        f"If the two times above disagree with each other by more than you "
+        f"expect, check the clock first: run `date -u` and compare it against "
+        f"a known-good source. A host whose clock runs fast will reject a "
+        f"license that is still valid."
+    )
+
+
+def _verify_license_jwt(token: str) -> dict:
+    """Verify RS256 signature and expiry. Returns decoded payload."""
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import padding
+
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise LicenseError("Malformed license key.")
+
+    header_b64, payload_b64, sig_b64 = parts
+    header = json.loads(_b64url_decode(header_b64))
+    if header.get("alg") != "RS256":
+        raise LicenseError("Invalid license key algorithm.")
+
+    message = f"{header_b64}.{payload_b64}".encode()
+    signature = _b64url_decode(sig_b64)
+
+    pub_key = serialization.load_pem_public_key(_get_public_key().encode())
+    try:
+        pub_key.verify(signature, message, padding.PKCS1v15(), hashes.SHA256())
+    except Exception:
+        raise LicenseError("License key signature is invalid.")
+
+    payload = json.loads(_b64url_decode(payload_b64))
+    exp = payload.get("exp")
+    if exp is not None and time.time() - CLOCK_SKEW_LEEWAY_SECONDS > exp:
+        trace("license", "jwt_expired", "License key has expired", level="error",
+              sub=payload.get("sub"))
+        raise LicenseError(_expiry_error(exp))
+
+    trace("license", "jwt_verified", "License JWT signature and expiry verified",
+          sub=payload.get("sub"))
+    return payload
+
+
+def credentials_dir(repo_root: str | os.PathLike[str] | None = None) -> Path:
+    """The directory holding this deployment's nkx credentials.
+
+    One resolver for instanceauth.py's `instance_nonce` and fingerprint.py's
+    `machine_signal`. Both modules used to carry their own copy of this
+    precedence and the copies did not agree with the Node port, which is how
+    PKG-02 happened: the copies fell back to the *process working directory*,
+    so `nkx-dev unlock ~/work/acme` run from anywhere else looked like a
+    brand-new machine, registered a fresh runtime instance and consumed a
+    licence seat — once per directory the command was ever run from.
+
+    NKX_CREDENTIALS_DIR wins when set. The runtime SDK's credential chain
+    resolves a directory and exports it before the loader runs, so a
+    deployment mounting credentials outside the repo keeps working.
+
+    Otherwise `<repo_root>/.nkx`, mirroring `nonceFilePath(repoRoot)` in
+    lang/javascript/instanceauth.js. `repo_root=None` means the caller has no
+    root in hand and accepts the working directory; every path that can
+    consume a seat passes one explicitly and must keep doing so.
+    """
+    cred_dir = os.environ.get("NKX_CREDENTIALS_DIR", "").strip()
+    if cred_dir:
+        return Path(cred_dir)
+    return (Path(repo_root) if repo_root is not None else Path(".")) / ".nkx"
+
+
+def _instance_fingerprint_header(repo_root: str | os.PathLike[str] | None = None) -> dict[str, str]:
+    """Best-effort X-Nkx-Instance-Fingerprint header for the validate call.
+
+    A fingerprint failure must never block the existing non-fatal revocation
+    check — on any exception this just omits the header. The backend treats a
+    missing header as "skip instance logic", which also keeps this
+    backwards-compatible with backend deployments that predate this feature.
+
+    `repo_root` is threaded so the fingerprint reads the same nonce file the
+    registration wrote. Without it the two halves can disagree — the nonce is
+    presented from `<repo>/.nkx` while the fingerprint hashes an empty string
+    read from the working directory — which silently degrades the signal the
+    backend uses to spot concurrent copies.
+    """
+    try:
+        from .fingerprint import get_fingerprint
+        return {"X-Nkx-Instance-Fingerprint": get_fingerprint(repo_root)}
+    except Exception as exc:
+        trace("license", "fingerprint_failed", f"fingerprint generation failed (non-fatal): {exc}",
+              level="warn")
+        return {}
+
+
+def _runtime_token_header() -> dict[str, str]:
+    """X-Nkx-Runtime-Token header for the derive call.
+
+    Only sent when NKX_RUNTIME_TOKEN is actually set — an absent header
+    keeps derive calls on a manifest without env_token binding unaffected,
+    and lets the backend distinguish "no token supplied" from "wrong token"
+    in its own denial reason.
+    """
+    token = _env_token()
+    return {"X-Nkx-Runtime-Token": token} if token else {}
+
+
+def _check_revocation_online(payload: dict, token: str) -> None:
+    """Phone-home revocation check.
+
+    `token` is the raw licence JWT, sent as `Authorization: Bearer`. The
+    endpoint used to accept the licence id alone, but that id is baked into
+    every deployed artifact, so anyone holding a copy of the software could
+    write events into the owning customer's audit trail. The key is the part
+    that is actually secret, and the backend now checks its `sub` against the
+    id in the URL.
+
+    Non-fatal on network errors for an ordinary license (the check itself
+    failing to reach the server doesn't block a legitimate offline/air-gapped
+    deployment) — but when the license JWT carries `require_online_validation:
+    true` (set by the backend for every customer-purpose license, see
+    licenseKeys.ts), both an unset NKX_VALIDATE_URL *and* a failed check
+    (timeout, connection error, DNS failure, malformed response) are fatal:
+    that claim exists specifically so an operator can't make a revoked
+    license run forever just by never setting the env var, or by blocking
+    egress to it.
+    """
+    license_id = payload["sub"]
+    validate_url = os.environ.get("NKX_VALIDATE_URL", "").rstrip("/")
+    if not validate_url:
+        if payload.get("require_online_validation"):
+            trace("license", "revocation_check_required", "NKX_VALIDATE_URL is required but unset",
+                  level="error", license_id=license_id)
+            raise LicenseError(
+                "This license requires online validation (NKX_VALIDATE_URL), "
+                "which is not configured. Set it in the deployment environment."
+            )
+        return
+    trace("license", "revocation_check_start", f"checking revocation for {license_id}",
+          license_id=license_id)
+    try:
+        import urllib.error
+        import urllib.request
+        req = urllib.request.Request(
+            f"{validate_url}/{license_id}",
+            headers={"Authorization": f"Bearer {token}", **_instance_fingerprint_header()},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=3) as r:
+                data = json.loads(r.read().decode())
+        except urllib.error.HTTPError as exc:
+            if exc.code in (401, 429):
+                # Neither is an answer about the licence, and neither may be
+                # read as one. 401 means this runtime failed to authenticate
+                # (no key, wrong key, or a backend that has rotated its signing
+                # keypair); 429 means it is simply going too fast. Falling
+                # through to the body below would parse `valid: false` out of
+                # either and tell the operator their licence had been revoked,
+                # which is the exact bug remotekek.js documents for a
+                # rate-limited derive: "it had not — the caller is going too
+                # fast, and the condition clears itself inside a minute".
+                #
+                # Raising here lands in the outer handler, which keeps the
+                # right semantics: non-fatal for an ordinary licence, fatal for
+                # one carrying require_online_validation. A check that could
+                # not be completed must never be scored as a pass.
+                raise RuntimeError(
+                    f"the validate endpoint answered {exc.code} "
+                    f"({'authentication failed' if exc.code == 401 else 'rate limited'}), "
+                    "which is not a verdict on the licence"
+                ) from exc
+            # The validate endpoint returns 410 (not 200) for a revoked,
+            # suspended or expired licence, which urlopen raises as an
+            # HTTPError rather than a normal response — read its body instead
+            # of treating it as a network error. It no longer answers about a
+            # *machine*: per-instance tracking left that endpoint in spec 16
+            # phase 5, and a copied deployment is stopped by revoking its
+            # runtime instance, which /internal/keys/derive enforces.
+            data = json.loads(exc.read().decode())
+        if not data.get("valid", True):
+            trace("license", "revocation_check_failed",
+                  f"License is invalid: {data.get('reason', 'unknown')}",
+                  level="error", license_id=license_id, reason=data.get("reason"))
+            raise LicenseError(
+                f"License is no longer valid ({data.get('reason', 'unknown')}). Contact your vendor."
+            )
+        trace("license", "revocation_check_end", "License is valid", license_id=license_id)
+    except LicenseError:
+        raise
+    except Exception as exc:
+        if payload.get("require_online_validation"):
+            # A license that demands online validation must fail closed on
+            # any network/parse error too — otherwise blocking egress to
+            # NKX_VALIDATE_URL (firewall, outage, unplugged NIC) is an easy
+            # way to keep a revoked license running forever (audit B10).
+            trace("license", "revocation_check_error",
+                  f"revocation check failed and is required: {exc}", level="error",
+                  license_id=license_id, error=str(exc))
+            raise LicenseError(
+                "This license requires online validation (NKX_VALIDATE_URL), "
+                f"but the check could not be completed: {exc}. "
+                "Contact your vendor if this persists."
+            ) from exc
+        trace("license", "revocation_check_error",
+              f"revocation check failed (non-fatal): {exc}", level="warn",
+              license_id=license_id, error=str(exc))
+
+
+# ── collectors ────────────────────────────────────────────────────────────────
+
+def _machine_id() -> str:
+    """Stable per-machine identifier (Linux / macOS / Windows)."""
+    # Linux
+    mid = Path("/etc/machine-id")
+    if mid.exists():
+        return mid.read_text().strip()
+    # macOS
+    try:
+        out = subprocess.check_output(
+            ["ioreg", "-rd1", "-c", "IOPlatformExpertDevice"],
+            stderr=subprocess.DEVNULL, text=True,
+        )
+        for line in out.splitlines():
+            if "IOPlatformUUID" in line:
+                return line.split('"')[-2]
+    except Exception:
+        pass
+    # Windows — motherboard UUID via WMIC (stable, hardware-bound)
+    try:
+        out = subprocess.check_output(
+            ["wmic", "csproduct", "get", "UUID"],
+            stderr=subprocess.DEVNULL, text=True,
+        )
+        for line in out.splitlines():
+            line = line.strip()
+            if line and line.upper() != "UUID":
+                return line
+    except Exception:
+        pass
+    return platform.node()  # hostname as last resort
+
+
+def _env_token() -> str:
+    """Operator-injected token from NKX_RUNTIME_TOKEN.
+
+    This is the recommended runtime factor: set it from Vault, KMS, or a
+    per-seat license key in your deployment pipeline. Its value is never
+    stored in the manifest — only its effect on the derived KEK is.
+    """
+    return os.environ.get("NKX_RUNTIME_TOKEN", "")
+
+
+def _aws_instance_id() -> str:
+    try:
+        import urllib.request
+        with urllib.request.urlopen(
+            "http://169.254.169.254/latest/meta-data/instance-id", timeout=1,
+        ) as r:
+            return r.read().decode().strip()
+    except Exception:
+        return ""
+
+
+def _gcp_instance_id() -> str:
+    try:
+        import urllib.request
+        req = urllib.request.Request(
+            "http://metadata.google.internal/computeMetadata/v1/instance/id",
+            headers={"Metadata-Flavor": "Google"},
+        )
+        with urllib.request.urlopen(req, timeout=1) as r:
+            return r.read().decode().strip()
+    except Exception:
+        return ""
+
+
+def _read_license_token() -> str:
+    """Read the raw license JWT from NKX_LICENSE_KEY or .nkx/license.key.
+
+    Does not verify the token or check revocation — just locates the raw
+    string. Shared by every caller that used to duplicate this lookup
+    (_license_key, check_license, is_developer_license) and by loader.py /
+    instanceauth.py / remotekek.py, which need the raw JWT itself (not just
+    its sub claim) to send as the derive/register call's Bearer token.
+    """
+    token = os.environ.get("NKX_LICENSE_KEY", "").strip()
+    if not token:
+        key_file = Path(".nkx") / "license.key"
+        if key_file.exists():
+            token = key_file.read_text().strip()
+    return token
+
+
+def _license_key() -> str:
+    """Return the stable license UUID for HKDF context binding.
+
+    At protect time (vendor container): reads NKX_LICENSE_UUID directly —
+    the backend injects the UUID without a signed JWT so the container doesn't
+    need the full token.
+
+    At runtime (customer environment): reads NKX_LICENSE_KEY (a RS256 JWT),
+    verifies its signature and expiry offline, optionally checks revocation via
+    NKX_VALIDATE_URL, then returns the stable license UUID (sub claim).
+    """
+    # Protect-time shortcut: UUID injected directly by the backend
+    direct_uuid = os.environ.get("NKX_LICENSE_UUID", "").strip()
+    if direct_uuid:
+        trace("license", "uuid_direct", "license UUID injected directly (protect-time)")
+        return direct_uuid
+
+    token = _read_license_token()
+    if not token:
+        trace("license", "missing", "No license key found", level="error")
+        raise LicenseError(
+            "No license key found. Set NKX_LICENSE_KEY or place the key in "
+            ".nkx/license.key"
+        )
+
+    payload = _verify_license_jwt(token)
+    _check_revocation_online(payload, token)
+    purpose = payload.get("purpose", "customer")
+    if purpose != "customer":
+        trace("license", "purpose_detected", f"license purpose: {purpose}",
+              sub=payload["sub"], purpose=purpose)
+    return payload["sub"]
+
+
+_COLLECTORS: dict[str, "callable[[], str]"] = {
+    "machine_id":     _machine_id,
+    "env_token":      _env_token,
+    "aws_instance_id": _aws_instance_id,
+    "gcp_instance_id": _gcp_instance_id,
+    "license_key":    _license_key,
+}
+
+AVAILABLE_SOURCES: list[str] = list(_COLLECTORS)
+
+
+# ── public API ────────────────────────────────────────────────────────────────
+
+def check_license(token: str = "") -> dict:
+    """Verify the license JWT and check revocation. Raises LicenseError on failure.
+    Returns the decoded JWT payload (callers that don't need it can ignore it).
+
+    Reads NKX_LICENSE_KEY env var or .nkx/license.key when no token
+    is given. Checks expiry offline always; checks revocation online when
+    NKX_VALIDATE_URL is set. Called by the loader at ProtectedFinder init
+    time (once per process start) — not on every import. The returned payload
+    is also passed to start_heartbeat_thread() so the heartbeat doesn't
+    re-verify the JWT signature on every beat.
+
+    All license purposes (customer / internal / developer) are accepted.
+    """
+    if not token:
+        token = _read_license_token()
+    if not token:
+        raise LicenseError(
+            "No license key found. Set NKX_LICENSE_KEY or place the key "
+            "in .nkx/license.key"
+        )
+    payload = _verify_license_jwt(token)
+    _check_revocation_online(payload, token)
+    return payload
+
+
+def start_heartbeat_thread(payload: dict) -> None:
+    """Background daemon thread that re-validates the license periodically so
+    a revoked or expired key is noticed by a long-running process rather than
+    only at startup. Since spec 16 phase 5 the backend's /licenses/validate/:id
+    answers about the *licence* only — per-machine tracking moved onto the
+    derive path, which knows which registered instance is asking.
+
+    Started once from ProtectedFinder.__init__ alongside the startup check,
+    only when NKX_VALIDATE_URL is actually configured (no point spinning
+    a thread that always no-ops). daemon=True so it never blocks process
+    exit. Heartbeat failures are logged via trace() and otherwise swallowed —
+    a flaky heartbeat must not crash an already-running customer process the
+    way a startup failure does. A heartbeat that discovers the license itself
+    was revoked mid-run is logged only, not enforced here — enforcement for a
+    running process is a deliberately out-of-scope product decision for this
+    feature (detection flags for review; it does not kill running processes).
+    """
+    if not os.environ.get("NKX_VALIDATE_URL", "").strip():
+        return
+
+    import threading
+    from .fingerprint import HEARTBEAT_INTERVAL_SECONDS
+
+    def _loop():
+        while True:
+            time.sleep(HEARTBEAT_INTERVAL_SECONDS)
+            try:
+                # Re-read rather than closing over one string: the heartbeat
+                # outlives any single call, and a key rotated on disk should be
+                # the one presented on the next tick.
+                _check_revocation_online(payload, _read_license_token())
+            except LicenseError as exc:
+                trace("license", "heartbeat_failed", str(exc), level="error",
+                      license_id=payload.get("sub"))
+            except Exception as exc:
+                trace("license", "heartbeat_error", f"heartbeat check failed (non-fatal): {exc}",
+                      level="warn", license_id=payload.get("sub"))
+
+    threading.Thread(target=_loop, daemon=True, name="nkx-license-heartbeat").start()
+
+
+def is_developer_license(token: str = "") -> bool:
+    """Return True if the license JWT grants developer / dev-mode access.
+
+    Reads NKX_LICENSE_KEY or .nkx/license.key when no token is given.
+    Returns False on any error — dev licenses fail open (no exception raised).
+
+    `kind` since spec 16 phase 2; `purpose` is the older spelling and still
+    what a token issued before that carries. Reading both matches
+    loader._derive_for_install() and the JS client's own devmode routing,
+    which have always done so. This function read `purpose` alone, so a
+    token carrying only the new claim would answer False here while those
+    two answered True — and the offline-developer branch in _install_core()
+    that gates on this would fall through to ProtectedFinder and report the
+    backend as unreachable instead of serving stubs. Latent rather than
+    live: the backend currently signs both claims on every licence
+    (backend/src/lib/licenseKeys.ts signLicense()), so the trigger is a
+    routine cleanup dropping the old one.
+    """
+    if not token:
+        token = _read_license_token()
+    if not token:
+        return False
+    try:
+        payload = _verify_license_jwt(token)
+        return (payload.get("kind") or payload.get("purpose")) == "developer"
+    except Exception:
+        return False
+
+def collect(sources: list[str], overrides: dict[str, str] | None = None) -> dict[str, str]:
+    """Run each named collector and return {source: value} mapping.
+
+    ``overrides`` lets callers supply a pre-known value for a source instead of
+    auto-collecting it.  Useful when the protect command runs in a container
+    that is not the target machine: pass the target machine's ID via
+    ``--machine-id`` so the manifest is bound to the right fingerprint.
+    """
+    ov = overrides or {}
+    result: dict[str, str] = {}
+    for src in sources:
+        if src in ov:
+            result[src] = ov[src]
+            continue
+        fn = _COLLECTORS.get(src)
+        if fn is None:
+            raise ValueError(
+                f"unknown runtime source: {src!r}. "
+                f"Available: {AVAILABLE_SOURCES}"
+            )
+        result[src] = fn()
+    return result
+
+
+_RESERVED_INFO_KEYS = frozenset({"build_id", "tenant_id", "customer_id", "purpose"})
+
+
+def assemble_info(
+    build_id: str,
+    tenant_id: str,
+    runtime_values: dict[str, str],
+    customer_id: str = "",
+    purpose: str = "",
+) -> bytes:
+    """Build deterministic HKDF info bytes from all context fields.
+
+    Length-prefixed encoding prevents field-boundary ambiguity (so
+    build_id="ab", tenant_id="c" ≠ build_id="a", tenant_id="bc").
+    Fields are sorted so insertion order doesn't affect the result.
+
+    customer_id and purpose are only included when non-empty, preserving
+    backward compatibility with existing v2 manifests that don't carry them.
+    Both are set *after* the runtime_values spread so they're always
+    authoritative — runtime_values may not define any reserved key itself
+    (build_id/tenant_id/customer_id/purpose); that would otherwise be
+    silently shadowed by this ordering rather than rejected outright.
+    """
+    collision = _RESERVED_INFO_KEYS & runtime_values.keys()
+    if collision:
+        raise ValueError(
+            f"runtime_values must not define reserved key(s): {sorted(collision)}"
+        )
+    h = hashlib.sha256()
+    h.update(b"nkx-context-v2\x00")
+    fields = {"build_id": build_id, "tenant_id": tenant_id, **runtime_values}
+    if customer_id:
+        fields["customer_id"] = customer_id
+    if purpose:
+        fields["purpose"] = purpose
+    for key in sorted(fields):
+        val = fields[key]
+        k_b, v_b = key.encode(), val.encode()
+        h.update(len(k_b).to_bytes(2, "big") + k_b)
+        h.update(len(v_b).to_bytes(4, "big") + v_b)
+    return h.digest()