code-sandboxes 1.7.0__tar.gz → 1.8.2__tar.gz

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/.github/workflows/build.yml

@@ -16,7 +16,7 @@ jobs:
     uses: ./.github/workflows/reusable-python.yml
     with:
       python-version: ${{ matrix.python-version }}
-      install-extras: test,typing
+      install-extras: test,typing,datalayer
       extra-packages: dbus-python keyring secretstorage
       run-tests: true
       test-command: pytest tests/ --cov=code_sandboxes --cov-report term-missing

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/.github/workflows/py-tests.yml

@@ -37,7 +37,7 @@ jobs:
     uses: ./.github/workflows/reusable-python.yml
     with:
       python-version: ${{ matrix.python-version }}
-      install-extras: test
+      install-extras: test,datalayer
       extra-packages: dbus-python keyring secretstorage
       run-tests: true
       test-command: pytest tests/ --cov=code_sandboxes --cov-report term-missing

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/.pre-commit-config.yaml

@@ -9,6 +9,11 @@ repos:
       - id: check-case-conflict
       - id: check-executables-have-shebangs
       - id: requirements-txt-fixer
+        # Datalayer's protected constraints (PLAN_ENV.md, E1-04): the header
+        # explains why it is ordered the way it is, and the fixer's sort
+        # would push that header below a package line rather than order the
+        # packages beneath it.
+        exclude: ^code_sandboxes/environments/constraints/sandbox-contract-v1\.txt$
       - id: check-added-large-files
       - id: check-case-conflict
       - id: check-toml

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/CHANGELOG.md

@@ -8,6 +8,54 @@
 
 ## Unreleased
 
+## 1.8.2
+
+- **A sandbox can be asked whether it is still alive, and the answer no longer
+  comes from a flag we set ourselves.** `CodeSandboxClient.is_alive()` returned
+  `is_started`, which records that `start()` ran in this process and nothing
+  else, so it kept answering `True` after the backend was gone. `Sandbox` now
+  carries an `is_alive()` that variants override; the Jupyter Server variant
+  looks its kernel id up on the server the way `_find_existing_kernel` lists
+  them, and the client asks the sandbox instead of reading its own flag.
+  Variants that have no way to ask their provider inherit the base answer,
+  `is_started`, which is all they can honestly say.
+- **Build secrets** (`environments.build_secrets`, PLAN_ENV.md E3-05).
+  `spec.buildSecrets` now resolves for real on the Datalayer variant: each
+  declared secret's value is fetched from IAM's own internal route at the
+  moment the `postInstall` step runs, mounted with BuildKit's
+  `--mount=type=secret` (an environment variable or a file under
+  `/run/secrets/`, per `mountAs`) in its own directory outside the build
+  context, and passed to `buildctl` by file path — never in argv, never in a
+  step result, never an `ARG`/`ENV` that would bake it into the image's
+  history. E2B and Daytona refuse a spec naming one outright: E0-04's spike
+  found only a registry login for the private base on either, never a
+  per-step arbitrary secret. A version with any build secret can never be
+  published to the Library (D-12). New codes `DL_ENV_BUILD_SECRET_UNAVAILABLE`
+  and `DL_ENV_PUBLICATION_BLOCKED`.
+
+## 1.8.0
+
+- **The Datalayer builder** (`environments.adapters.datalayer`, PLAN_ENV.md
+  E1-07). The Dockerfile is generated from the lock — `uv pip sync --require-hashes`, apt at the versions the lock recorded, `env` before
+  anything installs, `postInstall` as uid 1000 with no network — and the push
+  is by digest with an SBOM and provenance attestation, under the operability
+  tag `v<n>-<build_uid>` so a retried build cannot collide with the attempt
+  before it. `inspect`, `resolve`, `exists` and `delete` go through the ECR
+  API. Needs the `environments-builder` extra.
+- **The scan and the signature** (`environments.policy`,
+  `environments.attest`, E1-08, E1-09). A critical finding with a fixed
+  version blocks and one nothing fixes is recorded; the decision record keeps
+  the threshold it was decided under, so what stopped a build reads a month
+  later. cosign signs only once the scan passed, and a replay finds the
+  signature rather than pushing a second.
+- **A sandbox launches from an artifact** (E2-02): `Sandbox.create(artifact=…)`
+  hands each variant its own argument — an E2B template build, a Daytona
+  snapshot, a Modal image id through `Image.from_id`.
+- **Fixed, and a live defect:** Daytona's adapter took the image branch
+  whenever resources were requested, so a snapshot asked for with `cpu=` came
+  up from a plain Debian image running none of the snapshot's content, with
+  nothing saying so. The combination is refused (correction 13).
+
 ## 1.7.0
 
 - **A version is resolved into one lock** (`code_sandboxes.environments.resolve`,
@@ -56,8 +104,7 @@
   pinned exceptions left.
 
 - A Datalayer sandbox says when it is running code, so an interrupt can reach
-  it. `Sandbox.interrupt` refuses before it delegates — `if not
-  self._executing_event.is_set(): return False` — and `run_code` never set that
+  it. `Sandbox.interrupt` refuses before it delegates — `if not self._executing_event.is_set(): return False` — and `run_code` never set that
   event, so `is_executing` was always False, every interrupt was refused at the
   door, and the refusal was reported as "no code was running" to a caller
   watching a cell run.

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code_sandboxes
-Version: 1.7.0
+Version: 1.8.2
 Project-URL: Home, https://github.com/datalayer/code-sandboxes
 Author-email: Datalayer <info@datalayer.io>
 License: BSD 3-Clause License
@@ -73,6 +73,9 @@ Provides-Extra: docker
 Requires-Dist: docker>=6.0; extra == 'docker'
 Provides-Extra: e2b
 Requires-Dist: e2b-code-interpreter>=2.9.1; extra == 'e2b'
+Provides-Extra: environments-builder
+Requires-Dist: boto3>=1.34; extra == 'environments-builder'
+Requires-Dist: httpx>=0.27; extra == 'environments-builder'
 Provides-Extra: google-colab
 Provides-Extra: kaggle
 Requires-Dist: kaggle>=1.6; extra == 'kaggle'
@@ -85,6 +88,7 @@ Requires-Dist: modal>=1.5.2; extra == 'modal'
 Provides-Extra: monty
 Requires-Dist: pydantic-monty; extra == 'monty'
 Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
 Requires-Dist: ipykernel; extra == 'test'
 Requires-Dist: jupyter-server<3,>=1.6; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'test'

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/__version__.py

@@ -3,4 +3,4 @@
 
 """Code Sandboxes."""
 
-__version__ = "1.7.0"
+__version__ = "1.8.2"

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/base.py

@@ -198,6 +198,17 @@ class Sandbox(ABC):
         """Check if sandbox has been started."""
         return self._started
 
+    def is_alive(self) -> bool:
+        """Check whether the sandbox is still usable.
+
+        Distinct from :attr:`is_started`, which only records that `start` ran
+        in this process: a sandbox can be culled, evicted or shut down by
+        whoever else holds it, and nothing tells us. The base answer is
+        :attr:`is_started`, all a variant with no way to ask its provider can
+        honestly say; variants that can ask override this.
+        """
+        return self.is_started
+
     @property
     def is_executing(self) -> bool:
         """Check if the sandbox is currently executing code."""
@@ -508,6 +519,7 @@ class Sandbox(ABC):
         allowed_hosts: list[str] | None = None,
         tags: dict[str, str] | None = None,
         examples: list[tuple[str, str]] | None = None,
+        artifact: Any = None,
         **kwargs,
     ) -> Sandbox:
         """Factory method to create a sandbox of the specified variant.
@@ -589,6 +601,17 @@ class Sandbox(ABC):
 
         variant_value = normalize_variant(variant)
 
+        if artifact is not None:
+            # One neutral reference, translated into the argument its variant
+            # takes: a template build for E2B, a snapshot for Daytona, an
+            # image id for Modal (PLAN_ENV.md E2-02). A caller holding an
+            # Environment's artifact should not have to know which. What the
+            # caller passed itself wins, so naming both is not a surprise.
+            from .environments.builders import launch_arguments
+
+            for name_, value in launch_arguments(artifact, expected_variant=variant_value).items():
+                kwargs.setdefault(name_, value)
+
         if variant_value == "eval":
             sandbox = EvalSandbox(config=config, **kwargs)
         elif variant_value == "docker":
@@ -1066,7 +1089,7 @@ class Sandbox(ABC):
             from .exceptions import VariableNotFoundError
 
             raise VariableNotFoundError(name)
-        return _json.loads(printed[start + len(self._STDOUT_START):end])
+        return _json.loads(printed[start + len(self._STDOUT_START) : end])
 
     def set_variable(self, name: str, value: Any, context: Context | None = None) -> None:
         """Set a variable in the sandbox.

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/client.py

@@ -497,7 +497,14 @@ class CodeSandboxClient:
         return self._sandbox.interrupt()
 
     def is_alive(self) -> bool:
-        """Whether the sandbox is started and available for execution."""
+        """Whether the wrapped sandbox is still available for execution.
+
+        Asks the sandbox, which may check its provider. Sandboxes that expose
+        no liveness hook fall back to whether they report themselves started.
+        """
+        is_alive_fn = getattr(self._sandbox, "is_alive", None)
+        if callable(is_alive_fn):
+            return bool(is_alive_fn())
         return self.is_started
 
     def restart(self) -> None:

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/commands.py

@@ -284,7 +284,7 @@ print({_ENVELOPE_START!r} + __cmd_json__.dumps(__cmd_output__) + {_ENVELOPE_END!
                 duration=time.time() - start_time,
             )
         try:
-            result = json.loads(printed[start + len(_ENVELOPE_START):end])
+            result = json.loads(printed[start + len(_ENVELOPE_START) : end])
             return CommandResult(
                 exit_code=int(result["exit_code"]),
                 stdout=str(result["stdout"]),

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/datalayer_sandbox.py

@@ -55,7 +55,6 @@ from .models import (
     SnapshotInfo,
 )
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -580,10 +579,11 @@ class DatalayerSandbox(Sandbox):
         **This variant neither implemented it nor read the flag**, so the
         base class's default ran instead: it sets a flag, returns `True`, and
         stops nothing. (`google_colab` and `kaggle` are entitled to that
-        default — they poll `_interrupt_requested` and stop cooperatively.) Everything above believed it. `tasks/cancel` marks a
-        task `cancelled` and calls the interrupt registered by
-        `execute_cell`; the interrupt answered yes; the cell went on running
-        on a runtime that goes on being billed.
+        default — they poll `_interrupt_requested` and stop cooperatively.)
+        Everything above believed it. `tasks/cancel` marks a task `cancelled`
+        and calls the interrupt registered by `execute_cell`; the interrupt
+        answered yes; the cell went on running on a runtime that goes on
+        being billed.
 
         Measured on prod1 on 2026-09-07: a cell looping for two minutes,
         cancelled ten seconds in, `tasks/cancel` and `tasks/get` both
@@ -603,13 +603,11 @@ class DatalayerSandbox(Sandbox):
         """
         client = getattr(self._runtime, "sandbox_client", None)
         if client is None:
-            logger.warning(
-                "This sandbox has no runtime client, so nothing could be interrupted"
-            )
+            logger.warning("This sandbox has no runtime client, so nothing could be interrupted")
             return False
         try:
             return bool(client.interrupt())
-        except Exception as error:  # noqa: BLE001 - a failed interrupt is an answer
+        except Exception as error:
             logger.warning("The runtime's kernel could not be interrupted: %s", error)
             return False
 
@@ -817,7 +815,9 @@ class DatalayerSandbox(Sandbox):
         try:
             # Set environment variables if provided
             if envs:
-                env_code = "\n".join(f"import os; os.environ[{k!r}] = {v!r}" for k, v in envs.items())
+                env_code = "\n".join(
+                    f"import os; os.environ[{k!r}] = {v!r}" for k, v in envs.items()
+                )
                 self._runtime.execute(env_code)
 
             response = self._runtime.execute(code, timeout=execution_timeout)

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/daytona_sandbox.py

@@ -510,8 +510,13 @@ class DaytonaSandbox(Sandbox):
         given = {key: value for key, value in settings.items() if value}
         return daytona.DaytonaConfig(**given) if given else None
 
-    def _create_params(self, daytona: Any) -> Any:
-        """What to ask Daytona for, from the configuration of this sandbox."""
+    def _create_params(self, daytona: Any) -> Any:  # noqa: C901
+        """What to ask Daytona for, from the configuration of this sandbox.
+
+        Read top to bottom: what it refuses — a snapshot with resources, a
+        snapshot with an image — is the rule, and splitting the refusals
+        across helpers would hide them from the one place a reader looks.
+        """
         common: dict[str, Any] = {"labels": self._labels()}
         if self.config.env_vars:
             common["env_vars"] = dict(self.config.env_vars)
@@ -538,6 +543,27 @@ class DaytonaSandbox(Sandbox):
             common["auto_delete_interval"] = 0
         if self._spot:
             common.update(self._spot_params(resources))
+        if self._snapshot is not None:
+            # A snapshot carries the machine it was created for — Daytona bakes
+            # CPU, memory, disk and GPU into it, and it is region-scoped — so
+            # asking for resources beside one asks for two different machines.
+            # This used to take the image branch instead: the sandbox came up
+            # from a Debian image with the resources asked for, running none of
+            # the content the snapshot held, and nothing said so (PLAN_ENV.md
+            # correction 13, E2-02). A resource change is a new snapshot.
+            if resources is not None:
+                raise SandboxConfigurationError(
+                    "A Daytona snapshot carries its own CPU, memory, disk and GPU, so "
+                    "cpu=, memory= and gpu= cannot be passed with snapshot=: the sandbox "
+                    "would have come up from a plain image instead, with none of the "
+                    "snapshot's content. Create a snapshot for the machine you want, or "
+                    "pass image= with the resources."
+                )
+            if self._image is not None:
+                raise SandboxConfigurationError(
+                    "snapshot= and image= are two different things to start from; pass one. "
+                    "A snapshot is what an Environment build records for this variant."
+                )
         if self._image is not None or resources is not None:
             image = self._image
             if image is None:
@@ -547,6 +573,8 @@ class DaytonaSandbox(Sandbox):
                     else daytona.Image.debian_slim()
                 )
             return daytona.CreateSandboxFromImageParams(image=image, resources=resources, **common)
+        # No snapshot named and nothing asked for: Daytona's own default, which
+        # is what `snapshot=None` means to it.
         return daytona.CreateSandboxFromSnapshotParams(snapshot=self._snapshot, **common)
 
     def _spot_params(self, resources: Any | None) -> dict[str, Any]:

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/docker_sandbox.py

@@ -10,19 +10,18 @@ through `jupyter-kernel-client` to execute code.
 
 from __future__ import annotations
 
+import logging
 import os
 import tempfile
 import time
 import uuid
 
-import logging
-
 import requests
 
 from .base import Sandbox, marks_execution
-from .jupyter_ingress import interrupt_kernel_client
 from .exceptions import SandboxConfigurationError, SandboxNotStartedError
 from .interfaces import ISandboxClient
+from .jupyter_ingress import interrupt_kernel_client
 from .models import (
     CodeError,
     Context,

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/e2b_sandbox.py

@@ -527,11 +527,19 @@ class E2BSandbox(Sandbox):
                 on_result(translated)
 
         seconds = timeout if timeout is not None else self.config.timeout
+        # A language and a context are two ways of saying the same thing to
+        # E2B, and its SDK refuses both at once: "You can provide context or
+        # language, but not both at the same time." A context already carries
+        # the language it was created with, so the context wins when there is
+        # one — which is what check 14 of E0-04 found here (PLAN_ENV E2-02).
+        e2b_context = self._e2b_context(context)
+        chosen: dict[str, Any] = (
+            {"context": e2b_context} if e2b_context is not None else {"language": "python"}
+        )
         try:
             execution = self._sandbox.run_code(
                 code,
-                language="python",
-                context=self._e2b_context(context),
+                **chosen,
                 on_stdout=take_stdout,
                 on_stderr=take_stderr,
                 on_result=take_result,

{code_sandboxes-1.7.0 → code_sandboxes-1.8.2}/code_sandboxes/environments/__init__.py

@@ -15,6 +15,9 @@ provider-specific:
 
 - :mod:`.spec` — the canonical specification and its rules;
 - :mod:`.resolve` — the lock a version is resolved into, once (D-9);
+- :mod:`.policy` — whether an artifact's scan lets it be used (D-11);
+- :mod:`.accounts` — whose provider account a managed artifact lives in (D-8);
+- :mod:`.attest` — the scan and the signature it needs before anything runs it;
 - :mod:`.contract` — ``sandbox-contract/v1`` and the Dockerfile validator;
 - :mod:`.lifecycle` — the version states and their legal moves;
 - :mod:`.errors` — the error taxonomy every provider error maps into;
@@ -28,6 +31,8 @@ The builders themselves are in :mod:`.adapters`, loaded by variant.
 
 from __future__ import annotations
 
+from .accounts import account_fingerprints, fingerprint_matches, provider_account
+from .attest import Attestor, attest_artifact, signature_tag
 from .bases import APPROVED_BASES, ApprovedBase
 from .builders import (
     ArtifactReference,
@@ -50,6 +55,7 @@ from .contract import (
 )
 from .errors import ERROR_CODES, EnvironmentsError, ErrorCode, map_provider_error
 from .lifecycle import VersionState, build_outcome, can_transition, transition
+from .policy import DEFAULT_POLICY, PolicyDecision, ScanPolicy, decide, refuse_if_blocked
 from .resolve import (
     LOCK_FORMAT,
     BuildkitResolveRunner,
@@ -76,6 +82,7 @@ __all__ = [
     "API_VERSION",
     "APPROVED_BASES",
     "CONTRACT_V1",
+    "DEFAULT_POLICY",
     "ERROR_CODES",
     "LOCK_FORMAT",
     "SANDBOX_CONTRACT_V1",
@@ -83,8 +90,9 @@ __all__ = [
     "VARIANTS",
     "ApprovedBase",
     "ArtifactReference",
-    "BuildkitResolveRunner",
+    "Attestor",
     "BuildRequest",
+    "BuildkitResolveRunner",
     "CapabilityReport",
     "CapabilitySet",
     "CheckResult",
@@ -94,23 +102,32 @@ __all__ = [
     "EnvironmentsError",
     "ErrorCode",
     "LocalResolveRunner",
+    "PolicyDecision",
     "ResolveRunner",
     "SandboxContract",
+    "ScanPolicy",
     "ValidationResult",
     "VersionState",
+    "account_fingerprints",
+    "attest_artifact",
     "build_outcome",
     "can_transition",
     "canonical_digest",
     "canonical_json",
     "check_dockerfile",
+    "decide",
+    "fingerprint_matches",
     "get_builder",
     "locked_versions",
-    "merge_requirements",
     "map_provider_error",
+    "merge_requirements",
     "parse_environment",
     "parse_resolver_failure",
     "protected_pins",
+    "provider_account",
+    "refuse_if_blocked",
     "resolve_environment",
+    "signature_tag",
     "spec_digest",
     "spec_findings",
     "transition",

code_sandboxes-1.8.2/code_sandboxes/environments/accounts.py

@@ -0,0 +1,143 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""Whose provider account an artifact lives in (PLAN_ENV.md, D-8, E2-01).
+
+A managed-variant build runs with the **environment owner's** provider
+secret — their E2B team, their Daytona organization, their Modal workspace —
+and the artifact it produces exists only there. So a launch has to answer a
+question the artifact's reference cannot: *are the credentials in this
+caller's hands the ones that can see it?* A template id from another team is
+not a missing template, it is somebody else's; launching it would either fail
+obscurely or, worse, start something unrelated that happens to share a name.
+
+This module answers it without holding a secret and without asking a provider
+anything:
+
+- **A fingerprint is derived from the credentials themselves.** The account's
+  own identifier when the caller's configuration names one — Daytona's
+  organization, Modal's workspace — and otherwise a digest of the credential
+  that opens the account. A digest identifies the account exactly (the same
+  key always answers the same thing) and reveals nothing.
+- **An account answers to several names**, so both sides compute the whole set
+  and a match on any one is a match. That is what lets an artifact recorded
+  before the organization was configured still launch after it is.
+- **No provider call.** Asking E2B who a key belongs to would make a launch
+  wait on a third party to decide whether it may proceed, and would need a
+  credential scope the launch path does not otherwise need.
+
+The comparison is deliberately conservative: **no fingerprint on either side
+is not a match.** An artifact recorded by an older build, or a caller with no
+provider secret at all, is refused with `provider_account_mismatch` rather
+than let through — the failure of a refusal is a launch somebody has to
+retry, and the failure of a pass is a sandbox running in an account nobody
+chose.
+
+@module code_sandboxes.environments.accounts
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping, Sequence
+
+__all__ = [
+    "ACCOUNT_VARIABLES",
+    "CREDENTIAL_VARIABLES",
+    "account_fingerprints",
+    "fingerprint_matches",
+    "provider_account",
+]
+
+#: What names an account, per variant, when the caller's configuration says
+#: so. Read from the same variables the SDKs read, so a deployment that can
+#: reach a provider can also name its account there — nothing extra to set.
+ACCOUNT_VARIABLES: dict[str, tuple[str, ...]] = {
+    # Daytona takes the organization explicitly, and a JWT credential is only
+    # usable with it.
+    "daytona": ("DAYTONA_ORGANIZATION_ID",),
+    # Modal names the workspace in its profile; `MODAL_WORKSPACE` is what a
+    # deployment sets when it holds several.
+    "modal": ("MODAL_WORKSPACE", "MODAL_PROFILE"),
+    # E2B's API key belongs to a team, and its API answers which only to an
+    # access token — which a launch does not hold. A deployment that wants the
+    # team in the record sets it; otherwise the credential's digest stands for
+    # it.
+    "e2b": ("E2B_TEAM_ID",),
+}
+
+#: The credential whose digest stands for the account when nothing names it.
+#: The first variable present is used, so the pair of a token id and its
+#: secret digests on the id — the half that identifies, not the half that
+#: authenticates.
+CREDENTIAL_VARIABLES: dict[str, tuple[str, ...]] = {
+    "daytona": ("DAYTONA_API_KEY", "DAYTONA_JWT_TOKEN"),
+    "modal": ("MODAL_TOKEN_ID",),
+    "e2b": ("E2B_API_KEY",),
+}
+
+
+def _digest(value: str) -> str:
+    """A short, stable, non-reversible name for a credential.
+
+    Sixteen hex characters of sha256: enough that two accounts do not collide,
+    short enough to read in a record, and nothing anybody can turn back into
+    the key.
+    """
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:16]
+
+
+def account_fingerprints(variant: str, secrets: Mapping[str, str] | None) -> tuple[str, ...]:
+    """Every name the account these secrets open answers to, strongest first.
+
+    `("daytona:org-42", "daytona:cred-1f2e3d4c5b6a7980")` — the organization
+    the caller named, and the digest of the key that opens it. A build records
+    the first; a launch compares against all of them, so an artifact recorded
+    before the organization was configured still launches after it is.
+
+    Empty when the secrets open no account of this variant, which is a
+    refusal and not a pass: see the module docstring.
+    """
+    name = str(variant or "").strip().lower()
+    held = {
+        str(key): str(value) for key, value in (secrets or {}).items() if str(value or "").strip()
+    }
+    if not held:
+        return ()
+    found: list[str] = []
+    for variable in ACCOUNT_VARIABLES.get(name, ()):
+        value = held.get(variable, "").strip()
+        if value:
+            found.append(f"{name}:{value}")
+            break
+    for variable in CREDENTIAL_VARIABLES.get(name, ()):
+        value = held.get(variable, "").strip()
+        if value:
+            found.append(f"{name}:cred-{_digest(value)}")
+            break
+    return tuple(found)
+
+
+def provider_account(variant: str, secrets: Mapping[str, str] | None) -> str:
+    """The one fingerprint an artifact records: the strongest name available."""
+    found = account_fingerprints(variant, secrets)
+    return found[0] if found else ""
+
+
+def fingerprint_matches(recorded: str, held: Sequence[str] | Mapping[str, str] | None) -> bool:
+    """Whether an artifact recorded for `recorded` may be launched by `held`.
+
+    `held` is what :func:`account_fingerprints` answered for the caller, or
+    the caller's secrets to work it out from. Nothing recorded, or nothing
+    held, is **not** a match.
+    """
+    wanted = str(recorded or "").strip()
+    if not wanted:
+        return False
+    if isinstance(held, Mapping):
+        variant = wanted.split(":", 1)[0]
+        names: Sequence[str] = account_fingerprints(variant, held)
+    else:
+        names = list(held or ())
+    return wanted in {str(name).strip() for name in names if str(name).strip()}