keenv 0.1.0__tar.gz

keenv-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.3
+Name: keenv
+Version: 0.1.0
+Summary: Run a command with secrets pulled from a KeePass database into its environment
+Author: zombig
+Author-email: zombig <me@zombig.name>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Topic :: Security
+Classifier: Topic :: Utilities
+Requires-Dist: pydantic>=2
+Requires-Dist: pykeepass>=4.1
+Requires-Dist: pyyaml>=6
+Requires-Python: >=3.10
+Project-URL: Issues, https://github.com/oberon-systems/keenv/issues
+Project-URL: Repository, https://github.com/oberon-systems/keenv
+Description-Content-Type: text/markdown
+
+# keenv
+
+`keenv` puts secrets from a [KeePass](https://keepass.info/) database into the
+environment of one command and nowhere else. The values never reach a file, an
+`export`, or the shell history: they exist between unlocking the database and
+`exec`ing the command, and the process that held them is replaced.
+
+It is the tool the Oberon Systems keyring policy names for local secrets, and
+the way [indech](https://github.com/oberon-systems/indech) hands the Cloudflare
+R2 keys to OpenTofu.
+
+## Contents
+
+- [Why](#why)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [How it works](#how-it-works)
+- [Development](#development)
+
+## Why
+
+The usual ways of getting a secret into a process all leave it somewhere:
+`export` puts it in every child of the shell for the rest of the session, a
+`.env` full of plaintext puts it on disk, and `eval $(something)` puts it in
+the history file as well.
+
+`keenv` reads the value out of the database at the moment it is needed, builds
+the environment for exactly one command, and replaces itself with that command.
+There is no `keenv export` and no `keenv eval`, on purpose.
+
+## Installation
+
+```bash
+pip install keenv
+```
+
+The database itself is read in process through
+[pykeepass](https://github.com/libkeepass/pykeepass), so KeePassXC does not
+have to be installed.
+
+## Configuration
+
+`keenv` reads two files, both optional. `keenv.yaml` names the database and
+maps environment variables onto entries:
+
+```yaml
+vault: ~/Dropbox/oberon.kdbx
+keyfile: ~/.keys/oberon.keyx
+
+env:
+  AWS_ACCESS_KEY_ID:
+    entry: Oberon/R2/indech-state
+    field: username
+  AWS_SECRET_ACCESS_KEY:
+    entry: Oberon/R2/indech-state
+    field: password
+```
+
+`.env` is the same mapping in the shape people already write, where a value may
+be a `keenv://` reference instead of a literal:
+
+```dotenv
+AWS_ACCESS_KEY_ID=keenv://Oberon/R2/indech-state/username
+AWS_SECRET_ACCESS_KEY=keenv://Oberon/R2/indech-state/password
+TF_LOG=INFO
+```
+
+A reference is `keenv://<entry path>/<field>`. The last segment is the field
+and everything before it is the path to the entry, so a field whose name
+contains a slash cannot be addressed. `username`, `password`, `url`, `notes`
+and `title` are matched case-insensitively; any other name is looked up as a
+custom attribute, with its spelling preserved.
+
+Values that are not references pass through literally. A `#` only starts a
+comment at the beginning of a line, never in the middle of one, because a
+secret may contain it.
+
+The layers apply in this order, each one overriding the last:
+
+| Layer | Set by |
+| :--- | :--- |
+| `keenv.yaml` | `-c`, default `./keenv.yaml` |
+| `.env` | `-e`, default `./.env` |
+| the database path | `vault:`, then `KEENV_VAULT`, then `--vault` |
+| the key file path | `keyfile:`, then `KEENV_KEYFILE`, then `--keyfile` |
+
+A file that is not there is an empty layer, not an error. Having nothing to
+resolve after both layers is an error.
+
+`keenv.yaml` is validated against a
+[pydantic](https://docs.pydantic.dev/) model that rejects keys it does not
+know, so `vualt:` is reported as a mistake rather than quietly ignored.
+
+## Usage
+
+Run a command with the resolved environment:
+
+```bash
+keenv run -- tofu -chdir=circuits/live/ramnode/compute plan
+```
+
+Check that every reference still points at something, without printing any
+value:
+
+```bash
+keenv check
+```
+
+Expected output:
+
+```text
+AWS_ACCESS_KEY_ID            keenv://Oberon/R2/indech-state/UserName    20 chars
+AWS_SECRET_ACCESS_KEY        keenv://Oberon/R2/indech-state/Password    40 chars
+```
+
+Point at another database and another mapping:
+
+```bash
+keenv run --vault ~/other.kdbx -e deploy.env -- ./deploy.sh
+```
+
+Exit codes are `0` on success, `1` for anything `keenv` can explain, `2` for a
+usage mistake, and `127` when the command does not exist. Otherwise the exit
+code is the command's own, because the command replaces `keenv`.
+
+## How it works
+
+1. Both layers are read and merged into one list of variables.
+2. If any of them is a `keenv://` reference, the database is opened once. The
+   master password is asked for on `/dev/tty`, never on stdin, so a password
+   prompt can never swallow the first line of a pipe. A key file replaces the
+   prompt.
+3. Every reference is resolved from that one open database.
+4. The resolved variables are laid over a copy of the current environment and
+   handed to `os.execvpe`.
+
+Step 4 is what keeps the secrets contained: `execvpe` replaces the process
+image, so nothing that held the values is still running once the command
+starts, and the shell that invoked `keenv` never saw them.
+
+## Development
+
+```bash
+make init
+make test
+make lint
+```
+
+`make init` creates `.venv`, installs the package in editable mode and wires up
+the [pre-commit](https://pre-commit.com/) hooks. The test suite builds its own
+throwaway database in a temporary directory; no test opens a real vault.
+
+Commits go through [commitizen](https://commitizen-tools.github.io/commitizen/):
+
+```bash
+.venv/bin/cz commit
+```

keenv-0.1.0/README.md

@@ -0,0 +1,158 @@
+# keenv
+
+`keenv` puts secrets from a [KeePass](https://keepass.info/) database into the
+environment of one command and nowhere else. The values never reach a file, an
+`export`, or the shell history: they exist between unlocking the database and
+`exec`ing the command, and the process that held them is replaced.
+
+It is the tool the Oberon Systems keyring policy names for local secrets, and
+the way [indech](https://github.com/oberon-systems/indech) hands the Cloudflare
+R2 keys to OpenTofu.
+
+## Contents
+
+- [Why](#why)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [How it works](#how-it-works)
+- [Development](#development)
+
+## Why
+
+The usual ways of getting a secret into a process all leave it somewhere:
+`export` puts it in every child of the shell for the rest of the session, a
+`.env` full of plaintext puts it on disk, and `eval $(something)` puts it in
+the history file as well.
+
+`keenv` reads the value out of the database at the moment it is needed, builds
+the environment for exactly one command, and replaces itself with that command.
+There is no `keenv export` and no `keenv eval`, on purpose.
+
+## Installation
+
+```bash
+pip install keenv
+```
+
+The database itself is read in process through
+[pykeepass](https://github.com/libkeepass/pykeepass), so KeePassXC does not
+have to be installed.
+
+## Configuration
+
+`keenv` reads two files, both optional. `keenv.yaml` names the database and
+maps environment variables onto entries:
+
+```yaml
+vault: ~/Dropbox/oberon.kdbx
+keyfile: ~/.keys/oberon.keyx
+
+env:
+  AWS_ACCESS_KEY_ID:
+    entry: Oberon/R2/indech-state
+    field: username
+  AWS_SECRET_ACCESS_KEY:
+    entry: Oberon/R2/indech-state
+    field: password
+```
+
+`.env` is the same mapping in the shape people already write, where a value may
+be a `keenv://` reference instead of a literal:
+
+```dotenv
+AWS_ACCESS_KEY_ID=keenv://Oberon/R2/indech-state/username
+AWS_SECRET_ACCESS_KEY=keenv://Oberon/R2/indech-state/password
+TF_LOG=INFO
+```
+
+A reference is `keenv://<entry path>/<field>`. The last segment is the field
+and everything before it is the path to the entry, so a field whose name
+contains a slash cannot be addressed. `username`, `password`, `url`, `notes`
+and `title` are matched case-insensitively; any other name is looked up as a
+custom attribute, with its spelling preserved.
+
+Values that are not references pass through literally. A `#` only starts a
+comment at the beginning of a line, never in the middle of one, because a
+secret may contain it.
+
+The layers apply in this order, each one overriding the last:
+
+| Layer | Set by |
+| :--- | :--- |
+| `keenv.yaml` | `-c`, default `./keenv.yaml` |
+| `.env` | `-e`, default `./.env` |
+| the database path | `vault:`, then `KEENV_VAULT`, then `--vault` |
+| the key file path | `keyfile:`, then `KEENV_KEYFILE`, then `--keyfile` |
+
+A file that is not there is an empty layer, not an error. Having nothing to
+resolve after both layers is an error.
+
+`keenv.yaml` is validated against a
+[pydantic](https://docs.pydantic.dev/) model that rejects keys it does not
+know, so `vualt:` is reported as a mistake rather than quietly ignored.
+
+## Usage
+
+Run a command with the resolved environment:
+
+```bash
+keenv run -- tofu -chdir=circuits/live/ramnode/compute plan
+```
+
+Check that every reference still points at something, without printing any
+value:
+
+```bash
+keenv check
+```
+
+Expected output:
+
+```text
+AWS_ACCESS_KEY_ID            keenv://Oberon/R2/indech-state/UserName    20 chars
+AWS_SECRET_ACCESS_KEY        keenv://Oberon/R2/indech-state/Password    40 chars
+```
+
+Point at another database and another mapping:
+
+```bash
+keenv run --vault ~/other.kdbx -e deploy.env -- ./deploy.sh
+```
+
+Exit codes are `0` on success, `1` for anything `keenv` can explain, `2` for a
+usage mistake, and `127` when the command does not exist. Otherwise the exit
+code is the command's own, because the command replaces `keenv`.
+
+## How it works
+
+1. Both layers are read and merged into one list of variables.
+2. If any of them is a `keenv://` reference, the database is opened once. The
+   master password is asked for on `/dev/tty`, never on stdin, so a password
+   prompt can never swallow the first line of a pipe. A key file replaces the
+   prompt.
+3. Every reference is resolved from that one open database.
+4. The resolved variables are laid over a copy of the current environment and
+   handed to `os.execvpe`.
+
+Step 4 is what keeps the secrets contained: `execvpe` replaces the process
+image, so nothing that held the values is still running once the command
+starts, and the shell that invoked `keenv` never saw them.
+
+## Development
+
+```bash
+make init
+make test
+make lint
+```
+
+`make init` creates `.venv`, installs the package in editable mode and wires up
+the [pre-commit](https://pre-commit.com/) hooks. The test suite builds its own
+throwaway database in a temporary directory; no test opens a real vault.
+
+Commits go through [commitizen](https://commitizen-tools.github.io/commitizen/):
+
+```bash
+.venv/bin/cz commit
+```

keenv-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "keenv"
+version = "0.1.0"
+description = "Run a command with secrets pulled from a KeePass database into its environment"
+readme = "README.md"
+authors = [
+    { name = "zombig", email = "me@zombig.name" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2",
+    "pykeepass>=4.1",
+    "PyYAML>=6",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Topic :: Security",
+    "Topic :: Utilities",
+]
+
+[project.scripts]
+keenv = "keenv.cli:main"
+
+[project.urls]
+Repository = "https://github.com/oberon-systems/keenv"
+Issues = "https://github.com/oberon-systems/keenv/issues"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"

keenv-0.1.0/src/keenv/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

keenv-0.1.0/src/keenv/cli.py

@@ -0,0 +1,122 @@
+"""The keenv command line: resolve the plan, then hand the process over."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from .config import DEFAULT_CONFIG, DEFAULT_ENV, Binding, Plan, build
+from .uri import Reference
+from .vault import Vault
+
+USAGE_ERROR = 2
+NOT_FOUND = 127
+
+ACTIONS = (
+    ('run', 'run a command with the resolved environment'),
+    ('check', 'resolve every reference and report, without the values'),
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog='keenv',
+        description='Put KeePass secrets in the environment of one '
+                    'command and nowhere else.',
+    )
+    subparsers = parser.add_subparsers(dest='action', required=True)
+
+    for action, help_text in ACTIONS:
+        sub = subparsers.add_parser(action, help=help_text)
+        sub.add_argument(
+            '-c', '--config', type=Path, default=DEFAULT_CONFIG,
+            help=f'keenv.yaml to read (default: {DEFAULT_CONFIG})',
+        )
+        sub.add_argument(
+            '-e', '--env', type=Path, default=DEFAULT_ENV,
+            help=f'.env to read (default: {DEFAULT_ENV})',
+        )
+        sub.add_argument(
+            '--vault', type=Path, default=None,
+            help='database, overriding keenv.yaml and KEENV_VAULT',
+        )
+        sub.add_argument(
+            '--keyfile', type=Path, default=None,
+            help='key file for the database',
+        )
+
+    return parser
+
+
+def _split_command(argv: list[str]) -> tuple[list[str], list[str]]:
+    if '--' not in argv:
+        return argv, []
+    index = argv.index('--')
+    return argv[:index], argv[index + 1:]
+
+
+def _resolve(plan: Plan) -> dict[str, str]:
+    if not plan.bindings:
+        raise ValueError(
+            'nothing to resolve: no env in keenv.yaml and no .env',
+        )
+
+    vault = None
+    if any(isinstance(v, Reference) for v in plan.bindings.values()):
+        if plan.settings.vault is None:
+            raise ValueError(
+                'no vault: name it in keenv.yaml, in KEENV_VAULT '
+                'or with --vault',
+            )
+        vault = Vault(plan.settings.vault, plan.settings.keyfile)
+
+    return {
+        name: vault.field(value) if isinstance(value, Reference) else value
+        for name, value in plan.bindings.items()
+    }
+
+
+def _describe(name: str, binding: Binding, value: str) -> str:
+    source = str(binding) if isinstance(binding, Reference) else 'literal'
+    return f'{name:<28} {source:<52} {len(value)} chars'
+
+
+def _check(plan: Plan) -> int:
+    resolved = _resolve(plan)
+    for name, binding in plan.bindings.items():
+        print(_describe(name, binding, resolved[name]))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point. Returns an exit code; `run` never returns at all."""
+    given = list(sys.argv[1:] if argv is None else argv)
+    given, command = _split_command(given)
+    options = _parser().parse_args(given)
+
+    try:
+        plan = build(
+            options.config, options.env, options.vault, options.keyfile,
+        )
+
+        if options.action == 'check':
+            return _check(plan)
+
+        if not command:
+            print(
+                'keenv run needs a command: keenv run -- tofu plan',
+                file=sys.stderr,
+            )
+            return USAGE_ERROR
+
+        environment = dict(os.environ)
+        environment.update(_resolve(plan))
+        os.execvpe(command[0], command, environment)
+    except ValueError as exc:
+        print(f'keenv: {exc}', file=sys.stderr)
+        return 1
+    except FileNotFoundError:
+        print(f'keenv: command not found: {command[0]}', file=sys.stderr)
+        return NOT_FOUND
+
+    return 0

keenv-0.1.0/src/keenv/config.py

@@ -0,0 +1,155 @@
+"""Where the variables come from: keenv.yaml and .env, merged into a plan."""
+
+import os
+import re
+from pathlib import Path
+from typing import NamedTuple
+
+import yaml
+from pydantic import BaseModel, ConfigDict, ValidationError, field_validator
+
+from .uri import Reference, from_entry, is_reference, parse
+
+DEFAULT_CONFIG = Path('keenv.yaml')
+DEFAULT_ENV = Path('.env')
+
+# `export ` is accepted so a .env can also be sourced by hand. An inline `#`
+# is not a comment: a secret may legitimately contain one.
+ENV_LINE = re.compile(
+    r'^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$',
+)
+
+Binding = Reference | str
+
+
+class EntrySpec(BaseModel):
+    """One variable in keenv.yaml: which entry, and which field of it."""
+
+    model_config = ConfigDict(extra='forbid')
+
+    entry: str
+    field: str
+
+    @field_validator('entry', 'field')
+    @classmethod
+    def _not_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError('must not be empty')
+        return value
+
+
+class ConfigFile(BaseModel):
+    """The schema of keenv.yaml. Unknown keys are typos, so they fail."""
+
+    model_config = ConfigDict(extra='forbid')
+
+    vault: Path | None = None
+    keyfile: Path | None = None
+    env: dict[str, EntrySpec] = {}
+
+    @field_validator('vault', 'keyfile')
+    @classmethod
+    def _expand(cls, value: Path | None) -> Path | None:
+        return value.expanduser() if value else None
+
+
+class Settings(NamedTuple):
+    """Which database to open and how."""
+
+    vault: Path | None
+    keyfile: Path | None
+
+
+class Plan(NamedTuple):
+    """The database, and what to put in the environment."""
+
+    settings: Settings
+    bindings: dict[str, Binding]
+
+
+def _expand(value: str | None) -> Path | None:
+    return Path(value).expanduser() if value else None
+
+
+def _unquote(value: str) -> str:
+    quoted = len(value) >= 2 and value[0] == value[-1]
+    return value[1:-1] if quoted and value[0] in ('"', "'") else value
+
+
+def _explain(path: Path, error: ValidationError) -> str:
+    lines = [
+        '  {}: {}'.format(
+            '.'.join(str(part) for part in item['loc']) or '<root>',
+            item['msg'],
+        )
+        for item in error.errors()
+    ]
+    return '\n'.join([f'{path}:', *lines])
+
+
+def load_config(path: Path) -> Plan:
+    """Read a keenv.yaml. A missing file is an empty layer, not an error."""
+    if not path.is_file():
+        return Plan(Settings(None, None), {})
+
+    try:
+        document = yaml.safe_load(path.read_text(encoding='utf-8')) or {}
+    except yaml.YAMLError as exc:
+        raise ValueError(f'{path}: {exc}') from exc
+
+    try:
+        config = ConfigFile.model_validate(document)
+    except ValidationError as exc:
+        raise ValueError(_explain(path, exc)) from exc
+
+    bindings: dict[str, Binding] = {
+        name: from_entry(spec.entry, spec.field)
+        for name, spec in config.env.items()
+    }
+    return Plan(Settings(config.vault, config.keyfile), bindings)
+
+
+def load_env(path: Path) -> dict[str, Binding]:
+    """Read a .env. keenv:// values resolve, everything else is literal."""
+    if not path.is_file():
+        return {}
+
+    bindings: dict[str, Binding] = {}
+    text = path.read_text(encoding='utf-8')
+    for number, line in enumerate(text.splitlines(), 1):
+        if not line.strip() or line.lstrip().startswith('#'):
+            continue
+
+        match = ENV_LINE.match(line)
+        if not match:
+            raise ValueError(f'{path}:{number}: not a NAME=value line')
+
+        name, value = match.group(1), _unquote(match.group(2))
+        try:
+            bindings[name] = parse(value) if is_reference(value) else value
+        except ValueError as exc:
+            raise ValueError(f'{path}:{number}: {exc}') from exc
+
+    return bindings
+
+
+def build(
+    config_path: Path,
+    env_path: Path,
+    vault: Path | None = None,
+    keyfile: Path | None = None,
+) -> Plan:
+    """Merge both layers. .env beats keenv.yaml, the flags beat both."""
+    plan = load_config(config_path)
+    bindings = dict(plan.bindings)
+    bindings.update(load_env(env_path))
+
+    settings = Settings(
+        vault
+        or _expand(os.environ.get('KEENV_VAULT'))
+        or plan.settings.vault,
+        keyfile
+        or _expand(os.environ.get('KEENV_KEYFILE'))
+        or plan.settings.keyfile,
+    )
+    return Plan(settings, bindings)

keenv-0.1.0/src/keenv/uri.py

@@ -0,0 +1,68 @@
+"""The `keenv://` reference: which entry and field a variable comes from."""
+
+from typing import NamedTuple
+
+SCHEME = 'keenv://'
+
+# KeePass spells the built-in fields this way; anything else is a custom
+# attribute and keeps whatever spelling the reference used.
+STANDARD_FIELDS = {
+    'username': 'UserName',
+    'user': 'UserName',
+    'password': 'Password',
+    'url': 'URL',
+    'notes': 'Notes',
+    'title': 'Title',
+}
+
+
+class Reference(NamedTuple):
+    """An entry path inside the database plus the field to read from it."""
+
+    path: tuple[str, ...]
+    field: str
+
+    def __str__(self) -> str:
+        return SCHEME + '/'.join((*self.path, self.field))
+
+
+def normalize_field(field: str) -> str:
+    """Map a field onto its KeePass spelling, leaving custom ones be."""
+    field = field.strip()
+    return STANDARD_FIELDS.get(field.lower(), field)
+
+
+def is_reference(value: str) -> bool:
+    """Whether a value is a keenv:// reference rather than a literal."""
+    return value.startswith(SCHEME)
+
+
+def parse(value: str) -> Reference:
+    """Parse `keenv://Group/Sub/Entry/field` into a Reference.
+
+    The last segment is the field and everything before it is the path to the
+    entry, so a field name containing a slash cannot be addressed this way.
+    """
+    if not is_reference(value):
+        raise ValueError(f'not a keenv reference: {value!r}')
+
+    segments = value[len(SCHEME):].split('/')
+    if any(not segment for segment in segments):
+        raise ValueError(f'empty segment in reference: {value!r}')
+    if len(segments) < 2:
+        raise ValueError(
+            f'reference needs an entry path and a field: {value!r}',
+        )
+
+    return Reference(tuple(segments[:-1]), normalize_field(segments[-1]))
+
+
+def from_entry(entry: str, field: str) -> Reference:
+    """Build a Reference from the `entry:`/`field:` pair keenv.yaml uses."""
+    segments = [segment for segment in entry.split('/') if segment]
+    if not segments:
+        raise ValueError(f'entry path is empty: {entry!r}')
+    if not field.strip():
+        raise ValueError(f'field is empty for entry {entry!r}')
+
+    return Reference(tuple(segments), normalize_field(field))

keenv-0.1.0/src/keenv/vault.py

@@ -0,0 +1,83 @@
+"""Opening the KeePass database and reading single fields out of it."""
+
+import getpass
+from pathlib import Path
+
+from pykeepass import PyKeePass
+from pykeepass.exceptions import CredentialsError
+
+from .uri import Reference
+
+# KeePass field name -> the attribute pykeepass exposes it under.
+PROPERTIES = {
+    'UserName': 'username',
+    'Password': 'password',
+    'URL': 'url',
+    'Notes': 'notes',
+    'Title': 'title',
+}
+
+
+def prompt_password(vault: Path) -> str:
+    """Ask for the master password on the terminal, never on stdin.
+
+    Falling back to stdin would silently eat the first line of a pipe, so a
+    session without a terminal is an error the caller has to fix.
+    """
+    try:
+        with open('/dev/tty', 'w+', encoding='utf-8') as tty:
+            prompt = f'Master password for {vault}: '
+            return getpass.getpass(prompt, stream=tty)
+    except OSError as exc:
+        raise ValueError(
+            f'no terminal to ask for the master password of {vault}; '
+            'run keenv from a terminal or point it at a key file',
+        ) from exc
+
+
+class Vault:
+    """A KeePass database, opened once and read many times."""
+
+    def __init__(self, path: Path, keyfile: Path | None = None,
+                 password: str | None = None) -> None:
+        if not path.is_file():
+            raise ValueError(f'vault not found: {path}')
+        if keyfile is not None and not keyfile.is_file():
+            raise ValueError(f'key file not found: {keyfile}')
+        if password is None and keyfile is None:
+            password = prompt_password(path)
+
+        try:
+            self._database = PyKeePass(
+                str(path),
+                password=password,
+                keyfile=str(keyfile) if keyfile else None,
+            )
+        except CredentialsError as exc:
+            raise ValueError(
+                f'{path}: wrong master password or key file',
+            ) from exc
+        self.path = path
+
+    def field(self, reference: Reference) -> str:
+        """Read one field of one entry, or explain which half is missing."""
+        entry = self._database.find_entries(
+            path=list(reference.path), first=True,
+        )
+        if entry is None:
+            raise ValueError(
+                f'{self.path}: no entry at {"/".join(reference.path)}',
+            )
+
+        attribute = PROPERTIES.get(reference.field)
+        if attribute is not None:
+            value = getattr(entry, attribute)
+        else:
+            value = entry.get_custom_property(reference.field)
+
+        if value is None:
+            raise ValueError(
+                f'{self.path}: entry {"/".join(reference.path)} '
+                f'has no {reference.field} field',
+            )
+        return str(value)