diff --git a/.gitattributes b/.gitattributes index 8eb7cfd..67d9aa7 100644 --- a/.gitattributes +++ b/.gitattributes @@ -19,4 +19,3 @@ *.ico binary *.exe binary *.zip binary -docs/book/ binary diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f7869bc --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,91 @@ + +# Contributor Covenant 3.0 Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. + +We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language. + +With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including: + +1. Respecting the **purpose of our community**, our activities, and our ways of gathering. +2. Engaging **kindly and honestly** with others. +3. Respecting **different viewpoints** and experiences. +4. **Taking responsibility** for our actions and contributions. +5. Gracefully giving and accepting **constructive feedback**. +6. Committing to **repairing harm** when it occurs. +7. Behaving in other ways that promote and sustain the **well-being of our community**. + + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct. + +1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop. +2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people. +3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits. +4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community. +5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission. +6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group. +7. Behaving in other ways that **threaten the well-being** of our community. + +### Other Restrictions + +1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions. +2. **Failing to credit sources.** Not properly crediting the sources of content you contribute. +3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community. +4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors. + + +## Reporting an Issue + +Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. + +When an incident does occur, it is important to report it promptly. To report a possible violation, **send an email .** + +Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. + + +## Addressing and Repairing Harm + +**** + +If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped. + +1) Warning + 1) Event: A violation involving a single incident or series of incidents. + 2) Consequence: A private, written warning from the Community Moderators. + 3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations. +2) Temporarily Limited Activities + 1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation. + 2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members. + 3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over. +3) Temporary Suspension + 1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation. + 2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions. + 3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted. +4) Permanent Ban + 1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member. + 2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior. + 3) Repair: There is no possible repair in cases of this severity. + +This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community. + + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). + +Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/) + +For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion). diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9071cb4..e13e85c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,9 +1,7 @@ # Contributing to postmaster -postmaster is a standalone, format-neutral local secret materialization -engine. It decrypts encrypted secret inputs at process launch time and -injects them into a child process via environment variables, files, or -systemd credentials — then `execvp`s the target binary directly. +Postmaster decrypts local secret inputs, projects values into the application, +and replaces the launcher with the target binary through `execvp`. External contributions are welcome. @@ -12,24 +10,24 @@ project's [MIT license](../LICENSE) (inbound = outbound). ## Ground rules -- **The Justfile is the single source of truth.** The local git hooks - (lefthook) and CI both call the same `just` recipes, so what passes - locally passes in CI. Don't add a check to CI that isn't a `just` recipe. -- **The bar is enforced, not aspirational.** Clippy runs with `-D - warnings`, formatting is checked, and the dependency license/source - policy is gated. CI will not go green on a warning. -- **Real tests, not coverage theater.** New behavior needs a test that - would fail without the change. Match the existing unit/integration - style in the crate. +- **Keep checks in the Justfile.** Git hooks and workflow definitions call + the same recipes. Runner setup still needs separate verification, and a + local pass doesn't establish that hosted CI ran. Don't add a CI check + without a matching recipe. +- **Treat warnings as failures.** Clippy runs with `-D warnings`. + Formatting and dependency license, source, and advisory checks must pass. +- **Test the behavior.** Add a regression that fails without the change. + Match the crate's existing unit and integration tests. - **This is a security tool.** Secret material, private keys, and decrypted values are core to its purpose. Changes to the decrypt path, key handling, or injection modes get extra scrutiny. ## Getting set up -You need a recent stable Rust toolchain (`rustup` + the -`rust-toolchain.toml` will help), [`just`](https://just.systems), and +You need Rust 1.99.1 or newer, [`just`](https://just.systems), and [`lefthook`](https://lefthook.dev) for the git hooks. +`rust-toolchain.toml` selects the toolchain and required components through +`rustup`. ```sh git clone git@github.com:beardedeagle/postmaster.git @@ -40,31 +38,36 @@ just --list # see every available recipe ## The development loop -Run the full native gate before you push — it is exactly what CI runs: +Run the Rust gate before pushing. It includes native and release checks, +Linux-target Clippy, a locked build, and tests: ```sh -just ci-rust # fmt-check, clippy, build, test +just ci-rust # fmt-check, native/release/Linux clippy, build, test just ci # ci-rust + nix flake check just docs # mdBook build ``` +The GitHub workflow jobs currently use `if: false`, so hosted checks are +skipped. Run the recipes locally and report that distinction in the PR. + For dependency policy checks: ```sh -just deny # cargo deny check (advisories, bans, sources) +just deny # advisories, bans, licenses, sources +just audit # advisory database check, warnings fail ``` ## Submitting a change 1. Branch off `main` (`git switch -c fix/short-description`). -2. Make your change + add tests where appropriate. +2. Make the change and add tests where needed. 3. Run the full `just ci`. 4. Open a PR. Use the PR template. -5. Be patient — reviews will focus on correctness, security posture, and - consistency with the existing style. +5. Include verification evidence and unresolved limits. Reviews focus on + correctness, security, and consistency with the existing code. ## Reporting bugs and requesting features -Please use the GitHub issue templates. For security issues, see -`SECURITY.md` and report privately (GitHub Security Advisories or the -contact in that file). +Use the GitHub issue templates. For security issues, see +[Security policy](SECURITY.md) and report privately through advisories or the +contact in that file. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index ad8ecf3..81655b4 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -16,7 +16,8 @@ A clear description of the bug and what you expected instead. 2. 3. -A minimal repro (failing postmaster command, unit test, or exec.json config) is the fastest path to a fix. +A minimal repro (failing postmaster command, unit test, or exec.json +config) is the fastest path to a fix. ## Environment diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 129708e..ed586fd 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -1,40 +1,37 @@ -# Security Policy +# Security policy ## Supported versions -postmaster is pre-1.0 and ships from a single line of development. -Security fixes land on the latest release and on `main`; there are no -separately maintained release branches. Always run the latest release. +Postmaster is unreleased. `main` is the supported development line; +there are no released versions or separately maintained release branches. | Version | Supported | | ---------------- | --------- | -| latest release | ✅ | -| `main` | ✅ | -| older tags | ❌ | +| `main` | Yes | ## Reporting a vulnerability **This project handles secrets.** Private keys, decrypted environment values, and systemd/nix-darwin credentials are core to its purpose. -Please report security issues **privately** — do **not** open a public +Report security issues **privately**. Do **not** open a public issue, pull request, or discussion for anything security-sensitive. Preferred channels (either is fine): 1. **GitHub private advisory (recommended).** Open a report at - https://github.com/beardedeagle/postmaster/security/advisories/new + [security advisories](https://github.com/beardedeagle/postmaster/security/advisories/new). This keeps the discussion private and allows coordinated disclosure. -2. **Email.** Write to randy@heroictek.com. +2. **Email.** Write to . -Please include as much of the following as you can: +Include the following where available: - A description of the vulnerability and its potential impact. - Steps to reproduce (or a minimal proof-of-concept if safe to share). - Affected versions / commits. - Any suggested mitigation or fix. -We will acknowledge receipt quickly and work with you on a fix and -disclosure timeline. +We'll acknowledge the report and work with you on a fix and disclosure +timeline. diff --git a/.github/actions/setup-nix/action.yml b/.github/actions/setup-nix/action.yml new file mode 100644 index 0000000..291d4af --- /dev/null +++ b/.github/actions/setup-nix/action.yml @@ -0,0 +1,55 @@ +name: Setup Nix +description: >- + Install Nix via the official installer, integrity-verified against a + pinned sha256 before execution, enable flakes, and put nix on PATH for + later steps. In-repo composite: no third-party actions, no unverified + remote code. + +inputs: + installer-version: + description: Nix release version to install. + required: false + default: "2.34.7" + installer-sha256: + description: sha256 of the official install script for installer-version. + required: false + default: "e9d447ce3d2ff62d7ff9cb6ef401de6fa8acb148839dd00f7271945d7b638b14" + +runs: + using: composite + steps: + - name: Install Nix (integrity-verified) + shell: bash + env: + NIX_VERSION: ${{ inputs.installer-version }} + INSTALLER_SHA256: ${{ inputs.installer-sha256 }} + run: | + set -euo pipefail + if command -v nix >/dev/null 2>&1; then + echo "nix already available: $(command -v nix) -> $(nix --version)" + else + url="https://releases.nixos.org/nix/nix-${NIX_VERSION}/install" + tmp="$(mktemp "${TMPDIR:-/tmp}/nix-install.XXXXXX")" + # Verify the pinned digest BEFORE executing: a substituted or + # corrupted installer fails closed here, never runs. + curl -sSfL "$url" -o "$tmp" + if command -v sha256sum >/dev/null 2>&1; then + echo "${INSTALLER_SHA256} ${tmp}" | sha256sum -c - + else + echo "${INSTALLER_SHA256} ${tmp}" | shasum -a 256 -c - + fi + sh "$tmp" --daemon --yes --no-modify-profile + fi + # The installer does not put nix on PATH for subsequent GHA steps. + if [[ -n "${GITHUB_PATH:-}" ]]; then + echo "/nix/var/nix/profiles/default/bin" >> "$GITHUB_PATH" + fi + + - name: Enable nix-command and flakes + shell: bash + run: | + set -euo pipefail + mkdir -p "$HOME/.config/nix" + if ! grep -qxF 'extra-experimental-features = nix-command flakes' "$HOME/.config/nix/nix.conf" 2>/dev/null; then + printf '\nextra-experimental-features = nix-command flakes\n' >> "$HOME/.config/nix/nix.conf" + fi diff --git a/.github/actions/setup-nix/test.py b/.github/actions/setup-nix/test.py new file mode 100644 index 0000000..39b24ef --- /dev/null +++ b/.github/actions/setup-nix/test.py @@ -0,0 +1,47 @@ +"""Check Nix feature configuration without installing Nix. + +Run: python3 .github/actions/setup-nix/test.py [path-to-bash] +""" + +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import textwrap + + +action = (Path(__file__).resolve().parent / "action.yml").read_text() +section = action.split(" - name: Enable nix-command and flakes\n", 1)[1] +body = textwrap.dedent(section.split(" run: |\n", 1)[1]) +bash = sys.argv[1] if len(sys.argv) > 1 else "/bin/bash" +cases = { + "missing": None, + "empty": "", + "nix-command-only": "experimental-features = nix-command\n", + "flakes-only": "experimental-features = flakes\n", + "commented": "# experimental-features = nix-command flakes\n", + "other-features": "experimental-features = ca-derivations\n", + "enabled": "experimental-features = nix-command flakes\n", + "no-newline": "experimental-features = nix-command", +} +for name, original in cases.items(): + with tempfile.TemporaryDirectory(prefix="postmaster-nix features-") as home: + config = Path(home) / ".config/nix/nix.conf" + if original is not None: + config.parent.mkdir(parents=True) + config.write_text(original) + env = {**os.environ, "HOME": home} + subprocess.run([bash, "-c", body], env=env, check=True) + first = config.read_text() + assert first.startswith(original or ""), f"{name}: existing config changed" + features = set() + for line in first.splitlines(): + key, separator, value = line.split("#", 1)[0].partition("=") + if separator and key.strip() in ("experimental-features", "extra-experimental-features"): + features.update(value.split()) + assert {"nix-command", "flakes"} <= features, f"{name}: missing features" + subprocess.run([bash, "-c", body], env=env, check=True) + assert config.read_text() == first, f"{name}: repeated setup changes config" + +print(f"Nix feature setup: {len(cases)} cases pass") diff --git a/.github/actions/setup-rust/action.yml b/.github/actions/setup-rust/action.yml new file mode 100644 index 0000000..1bc8e1c --- /dev/null +++ b/.github/actions/setup-rust/action.yml @@ -0,0 +1,113 @@ +name: Setup Rust and just +description: Install the pinned Rust toolchain (from rust-toolchain.toml), just, and optional cargo tools. + +inputs: + targets: + description: Optional space-separated list of additional Rust targets to install. + required: false + default: "" + install-just: + description: Whether to install the pinned just command runner. + required: false + default: "true" + just-version: + description: just runner version to install (not the Rust compiler version). + required: false + default: "1.51.0" + install-cargo-deny: + description: Whether to install cargo-deny. + required: false + default: "false" + install-cargo-audit: + description: Whether to install cargo-audit. + required: false + default: "false" + cargo-deny-version: + description: cargo-deny version to install. + required: false + default: "0.20.2" + cargo-audit-version: + description: cargo-audit version to install. + required: false + default: "0.22.2" + install-mdbook: + description: Whether to install mdbook and the mdbook-mermaid preprocessor (docs builds). + required: false + default: "false" + mdbook-version: + description: mdbook version to install. + required: false + default: "0.5.4" + mdbook-mermaid-version: + description: mdbook-mermaid preprocessor version to install. + required: false + default: "0.17.0" + install-target-dir: + description: Cargo target directory for tool installation builds. + required: false + default: target/cargo-install + +runs: + using: composite + steps: + - name: Install pinned Rust toolchain + shell: bash + env: + RUST_TARGETS: ${{ inputs.targets }} + run: | + set -euo pipefail + if ! command -v rustup >/dev/null 2>&1; then + echo "rustup must be preinstalled; refusing to run an unpinned remote installer" >&2 + exit 1 + fi + if [[ -n "${GITHUB_PATH:-}" ]]; then + echo "$HOME/.cargo/bin" >> "$GITHUB_PATH" + fi + # Refresh stable before resolving the repository's components and targets. + rustup update stable --no-self-update + rustup show + if [[ -n "$RUST_TARGETS" ]]; then + rustup target add $RUST_TARGETS + fi + + - name: Install just + if: ${{ inputs.install-just == 'true' }} + shell: bash + env: + JUST_VERSION: ${{ inputs.just-version }} + CARGO_INSTALL_TARGET_DIR: ${{ inputs.install-target-dir }} + run: | + set -euo pipefail + bash "$GITHUB_ACTION_PATH/install-tool.sh" just "$JUST_VERSION" "$CARGO_INSTALL_TARGET_DIR" + + - name: Install cargo-deny + if: ${{ inputs.install-cargo-deny == 'true' }} + shell: bash + env: + CARGO_DENY_VERSION: ${{ inputs.cargo-deny-version }} + CARGO_INSTALL_TARGET_DIR: ${{ inputs.install-target-dir }} + run: | + set -euo pipefail + bash "$GITHUB_ACTION_PATH/install-tool.sh" cargo-deny "$CARGO_DENY_VERSION" "$CARGO_INSTALL_TARGET_DIR" + + - name: Install cargo-audit + if: ${{ inputs.install-cargo-audit == 'true' }} + shell: bash + env: + CARGO_AUDIT_VERSION: ${{ inputs.cargo-audit-version }} + CARGO_INSTALL_TARGET_DIR: ${{ inputs.install-target-dir }} + run: | + set -euo pipefail + bash "$GITHUB_ACTION_PATH/install-tool.sh" cargo-audit "$CARGO_AUDIT_VERSION" "$CARGO_INSTALL_TARGET_DIR" + + - name: Install mdbook + if: ${{ inputs.install-mdbook == 'true' }} + shell: bash + env: + MDBOOK_VERSION: ${{ inputs.mdbook-version }} + MDBOOK_MERMAID_VERSION: ${{ inputs.mdbook-mermaid-version }} + CARGO_INSTALL_TARGET_DIR: ${{ inputs.install-target-dir }} + run: | + set -euo pipefail + bash "$GITHUB_ACTION_PATH/install-tool.sh" mdbook "$MDBOOK_VERSION" "$CARGO_INSTALL_TARGET_DIR" + bash "$GITHUB_ACTION_PATH/install-tool.sh" mdbook-mermaid "$MDBOOK_MERMAID_VERSION" "$CARGO_INSTALL_TARGET_DIR" diff --git a/.github/actions/setup-rust/install-tool.sh b/.github/actions/setup-rust/install-tool.sh new file mode 100644 index 0000000..d296f98 --- /dev/null +++ b/.github/actions/setup-rust/install-tool.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# Ensure a requested Cargo tool runs at its pinned version in later steps. +# Args: crate/binary name (string), version (string), build directory (path). +# Exits nonzero if installation fails or the resulting version differs. +set -euo pipefail + +tool="$1" +version="$2" +target_dir="$3" +install_root="${CARGO_INSTALL_ROOT:-${CARGO_HOME:-$HOME/.cargo}}" +tool_bin="$install_root/bin" +export PATH="$tool_bin:$PATH" + +version_matches() { + local reported + reported="$("$tool" --version 2>/dev/null)" || return 1 + [[ "$reported" == "$tool $version" || "$reported" == "$tool v$version" ]] +} + +if ! version_matches; then + cargo install "$tool" --version "$version" --locked --force \ + --root "$install_root" --target-dir "$target_dir" + hash -r +fi +if ! version_matches; then + echo "$tool: expected version $version after installation" >&2 + exit 1 +fi +if [[ -n "${GITHUB_PATH:-}" ]]; then + echo "$tool_bin" >> "$GITHUB_PATH" +fi +"$tool" --version diff --git a/.github/actions/setup-rust/test.py b/.github/actions/setup-rust/test.py new file mode 100644 index 0000000..8bb2593 --- /dev/null +++ b/.github/actions/setup-rust/test.py @@ -0,0 +1,201 @@ +"""Exercise Rust and Cargo tool setup without installing packages. + +Run: python3 .github/actions/setup-rust/test.py [path-to-bash] +""" + +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import textwrap + + +action_dir = Path(__file__).resolve().parent +action = (action_dir / "action.yml").read_text() +bash = Path(sys.argv[1] if len(sys.argv) > 1 else "/bin/bash").resolve() +tools = { + "just": ("Install just", "JUST_VERSION", "1.51.0"), + "cargo-deny": ("Install cargo-deny", "CARGO_DENY_VERSION", "0.20.2"), + "cargo-audit": ("Install cargo-audit", "CARGO_AUDIT_VERSION", "0.22.2"), + "mdbook": ("Install mdbook", "MDBOOK_VERSION", "0.5.4"), + "mdbook-mermaid": ("Install mdbook", "MDBOOK_MERMAID_VERSION", "0.17.0"), +} +scenarios = ( + "current", "outdated", "broken", "missing", "install-fails", "installed-wrong", + "custom-root", "default-home", +) +failures = [] +for tool, (step, version_var, version) in tools.items(): + section = action.split(f" - name: {step}\n", 1)[1].split("\n - name:", 1)[0] + body = textwrap.dedent(section.split(" run: |\n", 1)[1]) + for scenario in scenarios: + with tempfile.TemporaryDirectory(prefix="postmaster-setup-") as tmp: + root = Path(tmp) + home = root / "home" + home.mkdir() + cargo_home = root / "cargo home" + install_root = root / "install root" if scenario == "custom-root" else (home / ".cargo" if scenario == "default-home" else cargo_home) + bin_dir = install_root / "bin" + bin_dir.mkdir(parents=True) + shims = root / "shims" + shims.mkdir() + (shims / "bash").symlink_to(bash) + log = root / "install.log" + env = os.environ.copy() + env.pop("CARGO_INSTALL_ROOT", None) + env.update( + HOME=str(home), + PATH=f"{shims}:/usr/bin:/bin", + CARGO_HOME=str(cargo_home), + CARGO_INSTALL_TARGET_DIR=str(root / "build target"), + GITHUB_ACTION_PATH=str(action_dir), + GITHUB_PATH=str(root / "github-path"), + TEST_TOOL=tool, + TEST_VERSION=version, + TEST_LOG=str(log), + TEST_SCENARIO=scenario, + TEST_INSTALL_ROOT=str(install_root), + ) + if scenario == "default-home": + env.pop("CARGO_HOME", None) + if scenario == "custom-root": + env["CARGO_INSTALL_ROOT"] = str(install_root) + for name, (_, var, pinned) in tools.items(): + env[var] = pinned + # The other mdBook executable remains available at its pin. + executable = shims / name + prefix = "v" if name == "mdbook" else "" + reported = f"{name} {prefix}{pinned}" + if name == tool: + if scenario == "missing": + continue + reported = f"{name} 0.0.0" if scenario != "current" else reported + executable.write_text( + "#!/bin/sh\n" + + ("exit 127\n" if name == tool and scenario == "broken" + else f"printf '%s\\n' '{reported}'\n") + ) + executable.chmod(0o755) + cargo = shims / "cargo" + cargo.write_text("""#!/bin/bash +set -eu +printf '%s\\n' "$@" > "$TEST_LOG" +[[ "$TEST_SCENARIO" != install-fails ]] || exit 1 +mkdir -p "$TEST_INSTALL_ROOT/bin" +version="$TEST_VERSION" +[[ "$TEST_SCENARIO" != installed-wrong ]] || version=0.0.0 +printf '#!/bin/sh\\nprintf "%%s\\n" "%s %s"\\n' "$TEST_TOOL" "$version" > "$TEST_INSTALL_ROOT/bin/$TEST_TOOL" +chmod +x "$TEST_INSTALL_ROOT/bin/$TEST_TOOL" +""") + cargo.chmod(0o755) + result = subprocess.run( + [str(bash), "-c", body], + env=env, capture_output=True, text=True, + ) + try: + should_fail = scenario in ("install-fails", "installed-wrong") + assert (result.returncode != 0) == should_fail, result.stdout + result.stderr + assert log.exists() == (scenario != "current"), "wrong install decision" + if log.exists(): + args = log.read_text().splitlines() + assert args[:2] == ["install", tool], args + assert args[args.index("--version") + 1] == version, args + assert "--locked" in args, args + assert args[args.index("--root") + 1] == str(install_root), args + assert args[args.index("--target-dir") + 1] == env["CARGO_INSTALL_TARGET_DIR"], args + if not should_fail: + paths = Path(env["GITHUB_PATH"]).read_text().splitlines() + assert str(bin_dir) in paths, "verified install directory absent from PATH" + check = subprocess.run( + [tool, "--version"], + env={**env, "PATH": os.pathsep.join(paths + [env["PATH"]])}, + capture_output=True, text=True, + ) + assert check.returncode == 0, check.stderr + assert check.stdout.strip() in (f"{tool} {version}", f"{tool} v{version}") + except (AssertionError, ValueError, FileNotFoundError) as error: + failures.append(f"{tool}/{scenario}: {error}") + +rust_scenarios = ( + "outdated", "current", "fresh", "targets", "update-fails", "show-fails", + "target-fails", "missing", +) +section = action.split(" - name: Install pinned Rust toolchain\n", 1)[1].split("\n - name:", 1)[0] +body = textwrap.dedent(section.split(" run: |\n", 1)[1]) +for scenario in rust_scenarios: + with tempfile.TemporaryDirectory(prefix="postmaster-rustup-") as tmp: + root = Path(tmp) + home = root / "home" + home.mkdir() + shims = root / "shims" + shims.mkdir() + log = root / "rustup.log" + state = root / "version" + if scenario != "fresh": + state.write_text("1.99.1\n" if scenario == "current" else "1.98.0\n") + targets = "aarch64-unknown-linux-gnu wasm32-unknown-unknown" if scenario in ("targets", "target-fails") else "" + env = { + **os.environ, + "HOME": str(home), + "PATH": str(shims), + "GITHUB_PATH": str(root / "github-path"), + "RUST_TARGETS": targets, + "TEST_SCENARIO": scenario, + "TEST_RUSTUP_LOG": str(log), + "TEST_RUSTUP_STATE": str(state), + } + if scenario != "missing": + rustup = shims / "rustup" + rustup.write_text(r"""#!/bin/bash +set -eu +printf '%s\n' "$*" >> "$TEST_RUSTUP_LOG" +case "$1" in + update) + [[ "$*" == 'update stable --no-self-update' ]] || exit 2 + [[ "$TEST_SCENARIO" != update-fails ]] || exit 1 + printf '1.99.1\n' > "$TEST_RUSTUP_STATE" + ;; + show) + [[ "$TEST_SCENARIO" != show-fails ]] || exit 1 + [[ -f "$TEST_RUSTUP_STATE" ]] || printf '1.99.1\n' > "$TEST_RUSTUP_STATE" + ;; + target) + [[ "$TEST_SCENARIO" != target-fails ]] || exit 1 + ;; + *) exit 2 ;; +esac +""") + rustup.chmod(0o755) + result = subprocess.run( + [str(bash), "-c", body], env=env, capture_output=True, text=True, + timeout=10, + ) + try: + should_fail = scenario in ("update-fails", "show-fails", "target-fails", "missing") + assert (result.returncode != 0) == should_fail, result.stdout + result.stderr + calls = log.read_text().splitlines() if log.exists() else [] + if not should_fail: + assert state.read_text().strip() == "1.99.1", "stable remains below the required Rust version" + assert "show" in calls, "repository components and targets were not resolved" + if scenario == "outdated": + assert calls.index("update stable --no-self-update") < calls.index("show"), calls + expected_targets = [f"target add {targets}"] if targets else [] + assert [call for call in calls if call.startswith("target ")] == expected_targets, calls + elif scenario == "update-fails": + assert calls == ["update stable --no-self-update"], calls + elif scenario == "show-fails": + assert calls[-1] == "show", calls + elif scenario == "target-fails": + assert calls[-1] == f"target add {targets}", calls + else: + assert not calls, calls + assert "rustup must be preinstalled" in result.stderr, result.stderr + if scenario != "missing": + assert (root / "github-path").read_text().splitlines() == [str(home / ".cargo/bin")] + except (AssertionError, ValueError, FileNotFoundError, IndexError) as error: + failures.append(f"rustup/{scenario}: {error}") + +if failures: + raise SystemExit("\n".join(failures)) +print(f"Cargo tool setup: {len(tools) * len(scenarios)} cases pass; Rust toolchain setup: {len(rust_scenarios)} cases pass") diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d52b976..3603e1b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,7 +1,5 @@ name: CI -# Disabled: GitHub Actions budget exhausted. -# Remove the `if: false` on each job to re-enable. on: push: branches: [main] @@ -22,7 +20,6 @@ jobs: quality: name: Quality (${{ matrix.os }}) runs-on: ${{ matrix.os }} - if: false timeout-minutes: 30 strategy: fail-fast: false @@ -32,42 +29,14 @@ jobs: - macos-latest steps: - name: Checkout - uses: actions/checkout@v5 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - - name: Setup Rust - uses: dtolnay/rust-toolchain@stable - with: - components: rustfmt, clippy - - - name: Cache Cargo - uses: Swatinem/rust-cache@v2 - - - name: Check formatting - run: cargo fmt --all --check + - name: Setup Rust and just + uses: ./.github/actions/setup-rust - - name: Run Clippy - run: cargo clippy --all-targets -- -D warnings + - name: Quality gate (fmt, clippy, build, test) + run: just ci-rust - - name: Build - run: cargo build --locked - - - name: Test - run: cargo test --locked - - deny: - name: Dependency policy - runs-on: ubuntu-latest - if: false - timeout-minutes: 15 - steps: - - name: Checkout - uses: actions/checkout@v5 - with: - persist-credentials: false - - - name: Dependency policy (cargo-deny) - uses: EmbarkStudios/cargo-deny-action@v2 - with: - manifest-path: Cargo.toml +# The dependency-policy (cargo deny) job lives in security.yml. diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3bb9c88..934e0d8 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,7 +1,5 @@ name: Docs -# Disabled: GitHub Actions budget exhausted. -# Remove the `if: false` on each job to re-enable. on: push: branches: [main] @@ -25,19 +23,20 @@ jobs: build: name: Build book runs-on: ubuntu-latest - if: false timeout-minutes: 15 steps: - name: Checkout - uses: actions/checkout@v5 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - name: Install Nix - uses: DeterminateSystems/nix-installer-action@v16 + uses: ./.github/actions/setup-nix + + - name: Install just and mdbook + uses: ./.github/actions/setup-rust with: - extra-conf: | - experimental-features = nix-command flakes + install-mdbook: "true" - name: Build book - run: nix run nixpkgs#mdbook -- build docs + run: just docs diff --git a/.github/workflows/nix.yml b/.github/workflows/nix.yml index 2adf045..0d7f6f2 100644 --- a/.github/workflows/nix.yml +++ b/.github/workflows/nix.yml @@ -1,7 +1,5 @@ name: Nix -# Disabled: GitHub Actions budget exhausted. -# Remove the `if: false` on each job to re-enable. on: push: branches: [main] @@ -19,7 +17,6 @@ jobs: flake-check: name: flake check (${{ matrix.os }}) runs-on: ${{ matrix.os }} - if: false timeout-minutes: 30 strategy: fail-fast: false @@ -29,18 +26,21 @@ jobs: - macos-latest steps: - name: Checkout - uses: actions/checkout@v5 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - name: Install Nix - uses: DeterminateSystems/nix-installer-action@v16 + uses: ./.github/actions/setup-nix + + - name: Install just + uses: ./.github/actions/setup-rust with: - extra-conf: | - experimental-features = nix-command flakes + install-cargo-deny: "false" + install-cargo-audit: "false" - name: nix flake check - run: nix flake check + run: just flake-check - name: nix flake check (eval-only, all systems) - run: nix flake check --all-systems --no-build + run: just flake-check-eval-all diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index a878eee..12619ab 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -1,7 +1,5 @@ name: Security -# Disabled: GitHub Actions budget exhausted. -# Remove the `if: false` on each job to re-enable. on: schedule: # Run daily at 9am UTC @@ -12,11 +10,13 @@ on: - 'Cargo.toml' - 'Cargo.lock' - 'deny.toml' + - '.github/workflows/security.yml' pull_request: paths: - 'Cargo.toml' - 'Cargo.lock' - 'deny.toml' + - '.github/workflows/security.yml' workflow_dispatch: permissions: @@ -26,44 +26,35 @@ jobs: audit: name: Security Audit runs-on: ubuntu-latest - if: false timeout-minutes: 15 steps: - name: Checkout - uses: actions/checkout@v5 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - - name: Setup Rust - uses: dtolnay/rust-toolchain@stable - - - name: Cache cargo-audit - uses: actions/cache@v5 + - name: Setup Rust, just, and cargo-audit + uses: ./.github/actions/setup-rust with: - path: ~/.cargo/bin/cargo-audit - key: cargo-audit-0.20 - - - name: Install cargo-audit - run: | - if ! command -v cargo-audit &> /dev/null; then - cargo install cargo-audit --locked - fi + install-cargo-audit: "true" - - name: Run cargo-audit - run: cargo audit --deny warnings + - name: Security audit + run: just audit deny: name: Dependency Check runs-on: ubuntu-latest - if: false timeout-minutes: 15 steps: - name: Checkout - uses: actions/checkout@v5 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 with: persist-credentials: false - - name: Dependency policy (cargo-deny) - uses: EmbarkStudios/cargo-deny-action@v2 + - name: Setup Rust, just, and cargo-deny + uses: ./.github/actions/setup-rust with: - manifest-path: Cargo.toml + install-cargo-deny: "true" + + - name: Dependency policy + run: just deny diff --git a/.gitignore b/.gitignore index 2119da7..bf88633 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ # Rust build output -/postmaster/target/ target/ # Ignore build outputs from performing a nix-build or `nix build` command @@ -24,8 +23,16 @@ result-* # mdBook build output (docs/) /docs/book/ +# generated by the docs recipe from /CHANGELOG.md +docs/src/changelog.md + # Additional ignores .omc/ target/ docs/superpowers/ .superpowers/ +.aider* +.crush/ + +# zvec-grep workspace index — local, per-machine, rebuilt with `zg index` +.zvec-grep/ diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..450dce0 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,36 @@ +{ + // Keep Markdown rules and ignored paths together in the CLI configuration. + "config": { + // Prose is wrapped at 80; tables and code blocks legitimately exceed any fixed + // width (a multi-column row or a CLI line can't be 80 chars) and render fine. + "MD013": { "line_length": 80, "tables": false, "code_blocks": false }, + // Keep a Changelog repeats `### Added`/`### Changed` etc. under each release; + // allow same-named headings that are not siblings. + "MD024": { "siblings_only": true }, + // CLI blocks with `$` prompts that show expected output are fine. + "MD014": false, + // Mermaid blocks don't have a language tag. + "MD040": { "allowed_languages": ["mermaid", "", "text", "json", "nix", "console", "ini", "sh", "bash"] }, + // SUMMARY.md uses multiple `#` section headers for mdBook navigation. + "MD025": false, + // Table column style — reference docs use compact tables. + "MD060": false + }, + "ignores": [ + // Cargo and Rustdoc build output. + "target/", + // mdBook build output. + "docs/book/", + // Generated at docs-build time from the root CHANGELOG.md. + "docs/src/changelog.md", + // SUMMARY.md uses mdBook-required syntax (multiple `#` section headers and + // 4-space-nested entries) that MD025/MD007 flag but mdBook needs. + "docs/src/SUMMARY.md", + // Verbatim upstream Contributor Covenant — not house prose. + ".github/CODE_OF_CONDUCT.md", + // PR templates intentionally start with "## Summary" — MD041 is wrong for them. + ".github/pull_request_template.md", + // Local aider tool history (gitignored) — not repo content. + ".aider-desk/" + ] +} diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc deleted file mode 100644 index e4140c4..0000000 --- a/.markdownlint.jsonc +++ /dev/null @@ -1,16 +0,0 @@ -{ - // Prose is wrapped at 80; tables and code blocks legitimately exceed any fixed - // width (a multi-column row or a CLI line can't be 80 chars) and render fine. - "MD013": { "line_length": 80, "tables": false, "code_blocks": false }, - // Keep a Changelog repeats `### Added`/`### Changed` etc. under each release; - // allow same-named headings that are not siblings. - "MD024": { "siblings_only": true }, - // CLI blocks with `$` prompts that show expected output are fine. - "MD014": false, - // Mermaid blocks don't have a language tag. - "MD040": { "allowed_languages": ["mermaid", "", "text", "json", "nix", "console", "ini", "sh", "bash"] }, - // SUMMARY.md uses multiple `#` section headers for mdBook navigation. - "MD025": false, - // Table column style — reference docs use compact tables. - "MD060": false -} diff --git a/.markdownlintignore b/.markdownlintignore deleted file mode 100644 index f4a6958..0000000 --- a/.markdownlintignore +++ /dev/null @@ -1,9 +0,0 @@ -# mdBook build output. -docs/book/ - -# Generated at docs-build time from the root CHANGELOG.md. -docs/src/changelog.md - -# SUMMARY.md uses mdBook-required syntax (multiple `#` section headers and -# 4-space-nested entries) that MD025/MD007 flag but mdBook needs. -docs/src/SUMMARY.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 6619275..e820825 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,54 +1,167 @@ # Changelog -All notable changes to this project are documented in this file. +Version `0.1.0` is the first planned release. +Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] +## [0.1.0] - 2026-07-28 ### Added -- Standalone postmaster binary — a format-neutral local secret - materialization engine that decrypts encrypted inputs at process - launch time, injects them into a child process, and `execvp`s the - target binary. -- `.env` input adapter — wire-compatible with dotenvx-encrypted `.env` - files (ECIES/secp256k1 + HKDF-SHA256 + AES-256-GCM). -- `postmaster_bundle` JSON container format as a second input adapter. -- `KeyNaming` enum (Env, Bundle) for compile-time exhaustive adapter - dispatch — zero vtable overhead, controlled adapter set. -- Three injection modes: `env` (environment variables), `files` - (one-file-per-secret on RAM-backed filesystem), `credentials` - (systemd credentials via postmaster daemon). -- Four key sources: systemd credentials (`LoadCredential=`), files - (`.env.keys` on disk), macOS keychain, environment variables. -- `postmaster exec --check` for config shape validation (CI). -- `postmaster setup --recheck` for runtime key source verification - (host). -- `postmaster setup` interactive command — idempotent, creates keys - directory, verifies permissions, optionally seeds keychain (macOS). -- `postmaster cleanup --config ` subcommand for plaintext - secret file removal. Wired to `ExecStopPost` in systemd. -- `--verify-keys` flag on `exec` for stale key detection after rotation. -- `OFlags::CLOEXEC` on all `rustix::fs::open` call sites. -- RAM backing verification via `hdiutil info` on macOS. -- Pre-execvp zeroization of `KeyRing` and `Resolved` values. -- Symlink rejection at every secret path: `O_NOFOLLOW`, `fstat`, - `symlink_metadata`, `fchmod` on socket fd. -- External binary verification: `codesign -v` on macOS, root-owned - check on Linux. -- Input validation: NUL byte rejection, path traversal rejection, - identifier validation, no shell expansion invariant. -- Threat model documentation covering memory residency, hardening - inheritance across execvp, and the 5-stage secret pipeline. -- Nix flake with rust-overlay for hermetic builds independent of - nixpkgs channel rustc version. -- `preventSwap` defaults to `true` — per-service `MemorySwapMax=0`. -- Child reads secrets via `$KEY_FILE` pointers (Docker secrets / - systemd credentials / 12-factor `_FILE` convention). -- `verify_key_freshness` uses `KeyNaming::Env.metadata_prefix()`. -- Two security audits conducted (provider handoff + destination - handoff), all findings fixed. -- Memory hardening audit conducted, all findings fixed. -- 12 verified-safe security properties documented in the threat model. +- Provides a standalone, format-neutral secret materialization engine for + Linux and macOS. Postmaster decrypts local inputs, injects values into the + application, and replaces the launcher with the target binary through + `execvp`. +- Decrypts dotenvx-compatible `.env` files with ECIES/secp256k1, + HKDF-SHA256, and AES-256-GCM. +- Reads encrypted `postmaster_bundle` JSON containers alongside dotenv + inputs in `env` and `files` modes. Bundle entries support UTF-8 and binary + values; UTF-8 entries must decode successfully. +- Binds each bundle ciphertext to its entry name with AES-GCM AAD under + the `ecies-secp256k1-hkdf-sha256-aes-256-gcm-entry-aad` suite. + Postmaster owns the envelope decoder and uses released ECIES curve/HKDF + helpers and RustCrypto AES-GCM with key-schedule zeroization. +- Uses an exhaustive `KeyNaming` enum for dotenv and bundle adapter + dispatch. The key ring admits only the namespaces required by the + configured inputs. +- Loads private keys from systemd credentials, local key files, macOS + Keychain, or environment variables. Dotenv inputs use + `DOTENV_PRIVATE_KEY*`; bundles use `POSTMASTER_KEY`. +- Reads macOS Keychain items through the Security.framework API. +- Hides private-key terminal input and restores settings before pending + termination or suspend signals. Failed or interrupted terminal reads discard + unread input; successful reads retain queued values. Idle noncanonical reads + wait for input, and prompt failures restore settings before returning errors. + Forced key-file replacement verifies inode + identity and ownership before publishing a fresh owner-only file. +- Authorizes daemon dotenv files against trusted `env_file_sha256` hashes + before parsing or decryption, at startup and on every fetch. Multiple hashes + support staged rotation without changing the dotenvx ciphertext format. +- Selects key sources in order. Missing systemd credentials allow the next + source; file, Keychain, and environment sources are terminal and fail + closed when unavailable or invalid. +- Checks private key files through an opened descriptor for ownership and + restrictive permissions. It rejects final-component symlinks and private + key paths in the Nix store. On macOS, runtime loading and file-source setup + rechecks reject untrusted read or mutation ACL grants without changing files. +- Keeps runtime key loading and setup verification on the same + key-variable naming rules. Environment loading skips non-UTF-8 entries. +- Supports `env` mode for direct environment injection. +- Supports `files` mode with one file per secret, `KEY_FILE` pointers, + and optional environment passthrough. Deployment integrations provide + RAM-backed storage and configure swap, dump, and cleanup policies. +- Supports `credentials` mode with pointers to systemd credentials or + selected values fetched from local Postmaster sockets. +- Resolves dotenv files before bundles. The first file defining a name + wins unless `overload` selects the last; the last assignment within one + dotenv file wins. Existing environment values take precedence unless + overload is enabled. +- Rejects undecryptable dotenv values by default. With `strict: false`, + it logs and omits those values; `--verify-keys` makes any omission fatal. + Bundle authentication failures always abort the launch. +- Rejects private-key variable names in bundles and removes recognized + private-key variables from the application's environment after + projection, regardless of key source or mode. +- Validates identifiers, credential-source path components, and NUL bytes + at the relevant input and projection boundaries. Encrypted values reach + the application without shell evaluation. Plaintext dotenv values follow + dotenv parsing rules, including variable substitution. +- Zeroizes the key ring and resolved value buffers before launch. + `KeyRing` and `Resolution` debug output redacts secret material. + ECIES secret-key debug output also redacts key bytes, and secret-key + comparisons use constant-time equality. +- Keeps the application as the service's main PID. A sibling monitor + forwards stop signals, allows a 250 ms grace period before SIGKILL, and + tracks service exit with Linux pidfds or macOS kqueue. It attempts file + cleanup after natural exit, forced termination, or a crash. +- Defers termination signals across the plaintext write window on Linux + and macOS. The monitor consumes signals synchronously; the launcher + restores its signal mask before exec. +- Pins the secrets directory for pruning, writes, cleanup, and monitoring. + File refreshes publish fresh 0600 inodes without writing new plaintext to + old open handles. Foreign, linked, and special existing entries fail closed. + Exported paths require trusted, protected ancestry; sticky shared parents + and trusted symlink aliases remain supported. +- Guards bulk cleanup with a `.postmaster-managed` sentinel. Bulk cleanup + retains the marker on failure so the operation can be retried. + Launch-failure cleanup uses the same pinned directory. +- Verifies macOS RAM backing through `mount` and `hdiutil info`. + The pinned directory must be beneath the configured mount, owned by the + service user, and on the verified RAM device. Mounted and partitioned + device rows stay associated with their own image; cross-device ancestor + symlinks fail the check. +- Opens ciphertext files with `O_NOFOLLOW` and sets `CLOEXEC` on the file + descriptors it opens. Config, bundle, and credential-response reads + enforce their documented size limits. Dotenv sources must be regular files; + parsing bounds source bytes, assignments, and expanded values before growth, + while syntax errors omit input contents. +- Verifies external tools before use with macOS code-signature checks or + Linux ownership and permission checks. Linux helpers reject group or other + write permissions. `id` lookup resolves system aliases, including NixOS + profiles, verifies the target and its directory ancestry, then invokes it. +- Validates daemon configuration at the root and nested credential + mappings. Startup rejects relative paths, symlinked socket parents, + and empty credentials. +- Applies a configured `peer_user` ACL independently of + `--allow-nonroot`. Socket permissions use a bind-time umask on Linux + and macOS, with the prior mask restored immediately afterward. +- Applies process hardening on secret-handling command paths and logs + failures. Help, version output, and structural config checks avoid + secret-path hardening work. +- Provides `postmaster exec --check` for offline config-shape validation. + The JSON Schema covers dotenv and bundle inputs, mode-specific fields, + and strict unknown-field handling. Tested examples exercise the parser + and guard schema agreement. +- Provides `postmaster exec --verify-keys` to check decryption before + launching with keys that may be stale after rotation. +- Provides interactive and unattended `postmaster setup` workflows. + Setup creates a `0700` keys directory, verifies owner-only key files, + and optionally seeds each required macOS Keychain account once. +- Provides `setup --recheck` for key-source accessibility checks and + `--keys-dir` for an explicit key directory. `--force` re-prompts for + key files or re-seeds Keychain items; force with unattended mode fails + closed. +- Provides `postmaster cleanup --config ` for managed + plaintext-file cleanup and `fetch` for local credential retrieval. +- Separates key handling, CLI parsing, and adapters into focused modules. + Monitor tests live beside the monitor module and run fork-based cases in + isolated processes. Adapter mapping tests live with the adapters, and + binary conformance tests cover each launch mode. +- Uses registry dependencies including base64 0.23.1, ecies 0.2.14, + serde 1.0.229, serde_json 1.0.154, zeroize 1.9.1, rustix 1.1.6, and + libc 0.2.191. AES-GCM 0.11.1 handles bundle authentication. +- Requires Rust 1.99.1 or newer. Release builds use LTO, stripped symbols, + overflow checks, and `panic = "abort"`. +- Provides a Nix package and overlay with rust-overlay for toolchain + selection. Service-manager bindings live in deployment integrations. +- Provides native and cross builds through the Justfile build matrix. + Cross builds use `cargo zigbuild`; builds preserve compiler flags and + profile overrides, and `max` builds remap source paths. +- Uses Justfile recipes for local checks and GitHub workflow definitions. + In-repo setup actions refresh stable before resolving the repository's + components and targets. Nix installation verifies + the pinned installer digest before execution. Official GitHub actions + and helper tools use pinned versions. Nix installer temporary files + work with GNU and macOS `mktemp`. + Nix setup extends existing feature settings with `nix-command` and `flakes`. + Cargo tool installation honors `CARGO_INSTALL_ROOT` and `CARGO_HOME` and + verifies the selected executables before adding their directory to `PATH`. +- Runs formatting, Clippy, and Markdown lint from pre-commit hooks. + Pre-push hooks run the Rust gate, dependency policy, and advisory checks. + The Rust gate includes native, release, and Linux-target Clippy; the + toolchain configuration includes `x86_64-unknown-linux-gnu`. +- Keeps Markdown lint rules in `.markdownlint-cli2.jsonc` and excludes + generated Cargo and mdBook output. Dependency policy checks duplicate + crate versions, sources, licenses, and advisories, with a documented + allowance for the wasm-gated `syn` duplicate. +- Exercises daemon startup, socket permissions, and real `fetch` + roundtrips in binary conformance tests. Regression tests cover read + limits, symlink refusal, partial-write and launch-failure cleanup, NUL + handling, precedence, provisioning permissions, key-source selection, + and monitor lifecycle behavior. +- Documents the launcher contract, five-stage secret pipeline, threat + model, deployment requirements, and memory-residency limits. The book + includes an executive overview, configuration examples, and monitor + lifecycle diagrams. +- Documents unsafe-code boundaries for signal deferral, monitoring, + macOS libc calls, systemd descriptor ownership, and test-only + environment mutation. diff --git a/Cargo.lock b/Cargo.lock index 2cdd0fc..732f0cb 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4,64 +4,72 @@ version = 4 [[package]] name = "aead" -version = "0.5.2" +version = "0.6.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0" +checksum = "1973cfbc1a2daf9cf550e74e1f088c28e7f7d8c1e1418fb6c9dc5184b7e84c99" dependencies = [ "crypto-common", - "generic-array", + "inout", ] [[package]] name = "aes" -version = "0.8.4" +version = "0.9.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0" +checksum = "fc0fc36d7440d015b45468ba08a21e80e056ebbd014c611c6298bb7503e04bd1" dependencies = [ - "cfg-if", "cipher", + "cpubits", "cpufeatures", + "zeroize", ] [[package]] name = "aes-gcm" -version = "0.10.3" +version = "0.11.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1" +checksum = "7f2b8006a0c83f52b62ba44a97b58bf76fe2f70a329e588f67f89691d93d498f" dependencies = [ "aead", "aes", "cipher", "ctr", + "ctutils", "ghash", - "subtle", + "zeroize", ] +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + [[package]] name = "base16ct" -version = "0.2.0" +version = "1.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4c7f02d4ea65f2c1853089ffd8d2787bdbc63de2f0d29dedbcf8ccdfa0ccd4cf" +checksum = "fd307490d624467aa6f74b0eabb77633d1f758a7b25f12bceb0b22e08d9726f6" [[package]] name = "base64" -version = "0.22.1" +version = "0.23.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" +checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5" [[package]] name = "bitflags" -version = "2.13.0" +version = "2.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8" +checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da" [[package]] name = "block-buffer" -version = "0.10.4" +version = "0.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa" dependencies = [ - "generic-array", + "hybrid-array", ] [[package]] @@ -78,25 +86,54 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" [[package]] name = "cipher" -version = "0.4.4" +version = "0.5.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad" +checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c" dependencies = [ + "block-buffer", "crypto-common", "inout", ] +[[package]] +name = "cmov" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a" + [[package]] name = "const-oid" -version = "0.9.6" +version = "0.10.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8" +checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c" + +[[package]] +name = "core-foundation" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6" +dependencies = [ + "core-foundation-sys", + "libc", +] + +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + +[[package]] +name = "cpubits" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae" [[package]] name = "cpufeatures" -version = "0.2.17" +version = "0.3.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566" dependencies = [ "libc", ] @@ -109,40 +146,53 @@ checksum = "790eea4361631c5e7d22598ecd5723ff611904e3344ce8720784c93e3d83d40b" [[package]] name = "crypto-bigint" -version = "0.5.5" +version = "0.7.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0dc92fb57ca44df6db8059111ab3af99a63d5d0f8375d9972e319a379c6bab76" +checksum = "914c195c4d7fbc5ed7f88d14cbf85914d5c664967658d43404b263913a477e82" dependencies = [ - "generic-array", - "rand_core", + "cpubits", + "ctutils", + "hybrid-array", + "num-traits", + "rand_core 0.10.1", "subtle", "zeroize", ] [[package]] name = "crypto-common" -version = "0.1.7" +version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453" dependencies = [ - "generic-array", - "typenum", + "hybrid-array", + "rand_core 0.10.1", ] [[package]] name = "ctr" -version = "0.9.2" +version = "0.10.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835" +checksum = "baaca1c4b237092596f64d571e9db6ce4109c4ef9742e27590f1709594461f21" dependencies = [ "cipher", ] +[[package]] +name = "ctutils" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "261af4dc7a06ea8a527a8717d8cbba3417530d6ea14e1edb3de6b67806be474f" +dependencies = [ + "cmov", + "subtle", +] + [[package]] name = "der" -version = "0.7.10" +version = "0.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb" +checksum = "6a996a108feb8b427a6e12fcf6af4aa83409b79d72c15337d7741368131ee004" dependencies = [ "const-oid", "zeroize", @@ -150,13 +200,14 @@ dependencies = [ [[package]] name = "digest" -version = "0.10.7" +version = "0.11.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2" dependencies = [ "block-buffer", + "const-oid", "crypto-common", - "subtle", + "ctutils", ] [[package]] @@ -167,18 +218,18 @@ checksum = "1aaf95b3e5c8f23aa320147307562d361db0ae0d51242340f558153b4eb2439b" [[package]] name = "ecies" -version = "0.2.11" +version = "0.2.14" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8a2df85e2b13a5f7fa61e7f0ee776acfe74da80bf2fb1bcde2725af19c197b33" +checksum = "7789c0aca3f3a992a12684c7a1089235faf38e399c7340a523f71bb4790f6e8b" dependencies = [ "aes-gcm", - "getrandom", + "getrandom 0.2.17", "hkdf", "k256", "lock_api", "once_cell", "parking_lot", - "rand_core", + "rand_core 0.6.4", "sha2", "typenum", "wasm-bindgen", @@ -186,16 +237,17 @@ dependencies = [ [[package]] name = "elliptic-curve" -version = "0.13.8" +version = "0.14.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b5e6043086bf7973472e0c7dff2142ea0b680d30e18d9cc40f267efbf222bd47" +checksum = "900f37e7e18d74a2347389af6cd69e3a30d5cc9e697f40004865679aa75e9c7c" dependencies = [ "base16ct", "crypto-bigint", + "crypto-common", "ff", - "generic-array", "group", - "rand_core", + "hybrid-array", + "rand_core 0.10.1", "sec1", "subtle", "zeroize", @@ -211,33 +263,39 @@ dependencies = [ "windows-sys", ] +[[package]] +name = "fastrand" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223" + [[package]] name = "ff" -version = "0.13.1" +version = "0.14.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c0b50bfb653653f9ca9095b427bed08ab8d75a137839d9ad64eb11810d5b6393" +checksum = "a1f686ab92a9fb0eaf188f6c6c87b89490baa6fdb0db4544ba4dc47f7942489f" dependencies = [ - "rand_core", + "rand_core 0.10.1", "subtle", ] [[package]] name = "futures-core" -version = "0.3.32" +version = "0.3.33" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d" +checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7" [[package]] name = "futures-task" -version = "0.3.32" +version = "0.3.33" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393" +checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109" [[package]] name = "futures-util" -version = "0.3.32" +version = "0.3.33" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6" +checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa" dependencies = [ "futures-core", "futures-task", @@ -245,17 +303,6 @@ dependencies = [ "slab", ] -[[package]] -name = "generic-array" -version = "0.14.7" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" -dependencies = [ - "typenum", - "version_check", - "zeroize", -] - [[package]] name = "getrandom" version = "0.2.17" @@ -269,24 +316,35 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "libc", + "r-efi", +] + [[package]] name = "ghash" -version = "0.5.1" +version = "0.6.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1" +checksum = "2eecf2d5dc9b66b732b97707a0210906b1d30523eb773193ab777c0c84b3e8d5" dependencies = [ - "opaque-debug", "polyval", + "zeroize", ] [[package]] name = "group" -version = "0.13.0" +version = "0.14.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f0f9ef7462f7c099f518d754361858f86d8a07af53ba9af0fe635bbccb151a63" +checksum = "7fd1a1c7a5206c5b7a3f5a0d7ccd3ff85d0c8f5133d62a02680255b0004af5f4" dependencies = [ "ff", - "rand_core", + "rand_core 0.10.1", "subtle", ] @@ -298,29 +356,40 @@ checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" [[package]] name = "hkdf" -version = "0.12.4" +version = "0.13.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7b5f8eb2ad728638ea2c7d47a21db23b7b58a72ed6a38256b8a1849f15fbbdf7" +checksum = "4aaa26c720c68b866f2c96ef5c1264b3e6f473fe5d4ce61cd44bbe913e553018" dependencies = [ "hmac", ] [[package]] name = "hmac" -version = "0.12.1" +version = "0.13.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e" +checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f" dependencies = [ "digest", ] +[[package]] +name = "hybrid-array" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27f864f10dfb56725ce5ce5472bc52252c8f93a4ab86327122cebf62c5f59a17" +dependencies = [ + "subtle", + "typenum", + "zeroize", +] + [[package]] name = "inout" -version = "0.1.4" +version = "0.2.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01" +checksum = "3a580c13f0ffc335ef42dd3f6b1a41b726051c5e1656d9a3aa6fddb3c5dfbbf9" dependencies = [ - "generic-array", + "hybrid-array", ] [[package]] @@ -342,20 +411,21 @@ dependencies = [ [[package]] name = "k256" -version = "0.13.4" +version = "0.14.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f6e3919bbaa2945715f0bb6d3934a173d1e9a59ac23767fbaaef277265a7411b" +checksum = "93f50113171a713f4a4231ef82eb26703607139b35dcb56241f0ceab2ae1f7d8" dependencies = [ - "cfg-if", + "cpubits", "elliptic-curve", - "once_cell", + "primeorder", + "wnaf", ] [[package]] name = "libc" -version = "0.2.186" +version = "0.2.191" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" [[package]] name = "linux-raw-sys" @@ -374,9 +444,18 @@ dependencies = [ [[package]] name = "memchr" -version = "2.8.2" +version = "2.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] [[package]] name = "once_cell" @@ -388,12 +467,6 @@ dependencies = [ "portable-atomic", ] -[[package]] -name = "opaque-debug" -version = "0.3.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381" - [[package]] name = "parking_lot" version = "0.12.5" @@ -425,64 +498,107 @@ checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" [[package]] name = "polyval" -version = "0.6.2" +version = "0.7.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25" +checksum = "f0fa31d631f2b2cb2a544d0aa321ce847a94764d701ca2becc411138b93d49cd" dependencies = [ - "cfg-if", + "cpubits", "cpufeatures", - "opaque-debug", "universal-hash", + "zeroize", ] [[package]] name = "portable-atomic" -version = "1.13.1" +version = "1.14.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49" +checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3" [[package]] name = "postmaster" version = "0.1.0" dependencies = [ + "aes-gcm", "base64", "dotenvy", "ecies", + "getrandom 0.4.3", "hex", "libc", "rustix", + "security-framework", "serde", "serde_json", + "sha2", + "tempfile", + "zeroize", +] + +[[package]] +name = "primefield" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c555a6e4eb7d4e158fcb028c835c3b8642206ddc279b5c6b202ef9a8bdb592f4" +dependencies = [ + "crypto-bigint", + "crypto-common", + "ff", + "rand_core 0.10.1", + "subtle", "zeroize", ] +[[package]] +name = "primeorder" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c9f42978c78a00e3d68f69fc03e57a234debae69da4020a4fb588fcdcd07b06" +dependencies = [ + "elliptic-curve", + "once_cell", + "primefield", + "wnaf", +] + [[package]] name = "proc-macro2" -version = "1.0.106" +version = "1.0.107" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" dependencies = [ "unicode-ident", ] [[package]] name = "quote" -version = "1.0.46" +version = "1.0.47" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" dependencies = [ "proc-macro2", ] +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + [[package]] name = "rand_core" version = "0.6.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" dependencies = [ - "getrandom", + "getrandom 0.2.17", ] +[[package]] +name = "rand_core" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" + [[package]] name = "redox_syscall" version = "0.5.18" @@ -494,9 +610,9 @@ dependencies = [ [[package]] name = "rustix" -version = "1.1.4" +version = "1.1.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190" +checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa" dependencies = [ "bitflags", "errno", @@ -507,9 +623,9 @@ dependencies = [ [[package]] name = "rustversion" -version = "1.0.22" +version = "1.0.23" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" [[package]] name = "scopeguard" @@ -519,22 +635,46 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" [[package]] name = "sec1" -version = "0.7.3" +version = "0.8.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d3e97a565f76233a6003f9f5c54be1d9c5bdfa3eccfb189469f11ec4901c47dc" +checksum = "d56d437c2f19203ce5f7122e507831de96f3d2d4d3be5af44a0b0a09d8a80e4d" dependencies = [ "base16ct", + "ctutils", "der", - "generic-array", + "hybrid-array", "subtle", "zeroize", ] +[[package]] +name = "security-framework" +version = "3.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d" +dependencies = [ + "bitflags", + "core-foundation", + "core-foundation-sys", + "libc", + "security-framework-sys", +] + +[[package]] +name = "security-framework-sys" +version = "2.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3" +dependencies = [ + "core-foundation-sys", + "libc", +] + [[package]] name = "serde" -version = "1.0.228" +version = "1.0.229" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" dependencies = [ "serde_core", "serde_derive", @@ -542,29 +682,29 @@ dependencies = [ [[package]] name = "serde_core" -version = "1.0.228" +version = "1.0.229" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" dependencies = [ "serde_derive", ] [[package]] name = "serde_derive" -version = "1.0.228" +version = "1.0.229" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 3.0.9", ] [[package]] name = "serde_json" -version = "1.0.150" +version = "1.0.154" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" dependencies = [ "itoa", "memchr", @@ -575,9 +715,9 @@ dependencies = [ [[package]] name = "sha2" -version = "0.10.9" +version = "0.11.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +checksum = "47d7069beb7d6ac7b9acd1039986e73443f24234f41074da099d6f994ac9ad19" dependencies = [ "cfg-if", "cpufeatures", @@ -604,15 +744,39 @@ checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" [[package]] name = "syn" -version = "2.0.118" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" dependencies = [ "proc-macro2", "quote", "unicode-ident", ] +[[package]] +name = "tempfile" +version = "3.27.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" +dependencies = [ + "fastrand", + "getrandom 0.4.3", + "once_cell", + "rustix", + "windows-sys", +] + [[package]] name = "typenum" version = "1.20.1" @@ -627,20 +791,14 @@ checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" [[package]] name = "universal-hash" -version = "0.5.1" +version = "0.6.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea" +checksum = "f4987bdc12753382e0bec4a65c50738ffaabc998b9cdd1f952fb5f39b0048a96" dependencies = [ "crypto-common", - "subtle", + "ctutils", ] -[[package]] -name = "version_check" -version = "0.9.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" - [[package]] name = "wasi" version = "0.11.1+wasi-snapshot-preview1" @@ -679,7 +837,7 @@ dependencies = [ "bumpalo", "proc-macro2", "quote", - "syn", + "syn 2.0.119", "wasm-bindgen-shared", ] @@ -707,14 +865,26 @@ dependencies = [ "windows-link", ] +[[package]] +name = "wnaf" +version = "0.14.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "795ca18b3fdb5e62bf982199278341ddcf7ebf7d32e25e212ad05d496e95f6fa" +dependencies = [ + "ff", + "group", + "hybrid-array", + "primefield", +] + [[package]] name = "zeroize" -version = "1.9.0" +version = "1.9.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e" +checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879" [[package]] name = "zmij" -version = "1.0.21" +version = "1.0.23" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/Cargo.toml b/Cargo.toml index f54c74d..64f09d0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,7 +2,7 @@ name = "postmaster" version = "0.1.0" edition = "2024" -rust-version = "1.96.1" +rust-version = "1.99.1" description = "standalone, format-neutral local secret materialization engine" license = "MIT" repository = "https://github.com/beardedeagle/postmaster" @@ -13,11 +13,20 @@ repository = "https://github.com/beardedeagle/postmaster" # We use a fairly strict set of lints. One deliberate deviation: we allow # `unsafe_code` (some stricter projects deny it outright). postmaster is a -# syscall-level socket-activation daemon and needs a handful of justified -# `unsafe` blocks (getpeereid(2), best-effort mlock()-style hardening, and -# UnixListener::from_raw_fd on the one inherited systemd fd) — each site in -# src/main.rs carries a SAFETY comment, so `unsafe_code` is left at rustc's -# default (allow) rather than denied or blanket-warned. +# syscall-boundary daemon and needs a handful of justified `unsafe` blocks: +# getpeereid(2) and PT_DENY_ATTACH on macOS (Darwin's stable kernel ABI is +# libc), signal-mask deferral around the plaintext-write window and the +# Darwin extended ACL inspection/clearing, test-only pseudo-terminals, and the +# sibling launch monitor (fork + pidfd/kqueue liveness — see +# docs/src/unsafe-code/monitor.md; on Linux the monitor's signal ops use +# rustix's linux_raw `runtime` API, fork(2) is the single libc FFI call), +# UnixListener::from_raw_fd on the inherited systemd sockets (Linux), and +# test-only set_var/remove_var (unsafe on edition 2024). Each site carries +# a SAFETY comment and is documented in docs/src/unsafe-code/ (the mdbook +# "Unsafe Code" section). mlockall/setrlimit/set_dumpable hardening uses +# SAFE rustix wrappers and is not part of the unsafe inventory. So +# `unsafe_code` stays at rustc's default (allow) rather than denied or +# blanket-warned. [lints.rust] future_incompatible = { level = "deny", priority = -1 } rust_2018_idioms = { level = "warn", priority = -1 } @@ -28,12 +37,14 @@ explicit_outlives_requirements = "warn" if_let_rescope = "warn" impl_trait_overcaptures = "warn" impl_trait_redundant_captures = "warn" -# `let _ = …` is postmaster's deliberate best-effort idiom: hardening calls -# (mlockall-style, non-dumpable, core limits, ptrace-deny) and cleanup paths -# (socket shutdown, stale-socket unlink, thread join at teardown) may -# legitimately fail, and the adjacent comments explain why that's acceptable. -# Converting them to unwrap/expect/error handling would CHANGE behavior in a -# fail-closed daemon, so the lint stays off. +# `let _ = …` is postmaster's deliberate best-effort idiom for cleanup +# paths (socket shutdown, stale-socket unlink, read-timeout set, thread +# join at teardown) that may legitimately fail, and the adjacent comments +# explain why that's acceptable. Security-relevant hardening calls +# (mlockall-style, non-dumpable, core limits, ptrace-deny) LOG their +# failures instead. Converting either to +# unwrap/expect/error handling would CHANGE behavior in a fail-closed +# daemon, so the lint stays off. let_underscore_drop = "allow" macro_use_extern_crate = "warn" meta_variable_misuse = "warn" @@ -70,6 +81,7 @@ fallible_impl_from = "warn" inefficient_to_string = "warn" macro_use_imports = "warn" match_same_arms = "warn" +multiple_crate_versions = "warn" no_effect_underscore_binding = "warn" panic = "warn" print_stderr = "warn" @@ -88,23 +100,49 @@ used_underscore_binding = "warn" # Wire-compatible with eciesjs (dotenvx's crypto): secp256k1 + HKDF-SHA256 + # AES-256-GCM with the ecies family's 16-byte nonce default. `pure` selects # the RustCrypto AES backend — no openssl in the closure. -ecies = { version = "0.2.11", default-features = false, features = ["pure", "secp256k1", "std"] } +ecies = { version = "0.2.14", default-features = false, features = ["pure", "secp256k1", "std"] } +# The bundle adapter owns its AAD envelope; RustCrypto performs AES-GCM. +aes-gcm = { version = "0.11.1", default-features = false, features = ["aes", "zeroize"] } dotenvy = "0.15" serde = { version = "1", features = ["derive"] } serde_json = "1" -base64 = "0.22" +base64 = "0.23" hex = "0.4" zeroize = "1" +sha2 = "0.11" +getrandom = "0.4" # Syscall layer: rustix's default linux_raw backend issues raw syscalls from -# Rust — no libc FFI in these paths, and the unsafe surface collapses to the -# single fd-ownership assertion at the systemd socket-activation boundary. -rustix = { version = "1", features = ["net", "process", "mm", "fs"] } +# Rust. Signal-mask operations and systemd fd adoption require narrow unsafe +# blocks; fork(2) uses libc at the launcher boundary. +rustix = { version = "1", features = ["net", "process", "mm", "fs", "termios", "event"] } + +[target.'cfg(target_os = "linux")'.dependencies] +# Linux-only additions for the sibling launch monitor +# (docs/src/unsafe-code/monitor.md): +# - rustix "runtime": the monitor's signal ops (mask for life, synchronous +# consumption) use kernel_sigprocmask/kernel_sigpending/kernel_sigwait — +# rustix's experimental runtime API (exported under a rotating module +# name) — so the Linux leg stays +# on linux_raw with NO libc signal FFI. Cargo.lock pins the exact rustix; +# an update that changes this unstable API fails the build loudly, +# never silently. +# - rustix "event": poll(2) on the service pidfd for liveness. +# - libc: fork(2) ONLY. rustix deliberately has no fork wrapper; this is +# the single libc FFI call on the Linux exec path (house-doctrine +# exception, review-gated — flagged in the unsafe-code registry). +rustix = { version = "1", features = ["runtime", "event"] } +libc = "0.2" [target.'cfg(target_os = "macos")'.dependencies] # Darwin's stable kernel ABI *is* libc (raw syscalls are unsupported there; -# rustix itself calls through libc on darwin). Two narrow calls use it -# directly: getpeereid for the peer check and PT_DENY_ATTACH hardening. +# rustix itself calls through libc on darwin). Narrow direct uses: getpeereid +# for the peer check, PT_DENY_ATTACH hardening, and the sibling monitor's +# kqueue/signal-mask ops (docs/src/unsafe-code/monitor.md). libc = "0.2" +security-framework = "3.7.0" + +[dev-dependencies] +tempfile = "3.27" [profile.release] # Everything here is stable-toolchain and arch-agnostic: safe under nixpkgs @@ -114,6 +152,10 @@ opt-level = 3 lto = "fat" codegen-units = 1 strip = "symbols" +# PT_DENY_ATTACH (macOS hardening) is gated on not(debug_assertions). +# Keep release builds covered by default; enabling debug assertions through +# a profile or environment override disables that call. +debug-assertions = false # Arithmetic bugs become panic → abort → Restart=on-failure: fail closed, # never a wrong answer. Cost is ~nil (crypto deps use wrapping intrinsics). overflow-checks = true diff --git a/Justfile b/Justfile index 5c70074..54d98ae 100644 --- a/Justfile +++ b/Justfile @@ -18,6 +18,14 @@ fmt-check: clippy: cargo +{{stable_toolchain}} clippy --all-targets -- -D warnings +# Check release-only code paths with Clippy. +clippy-release: + cargo +{{stable_toolchain}} clippy --all-targets --release -- -D warnings + +# Check Linux-only code paths; rust-toolchain.toml declares the target. +clippy-linux: + cargo +{{stable_toolchain}} clippy --all-targets --target x86_64-unknown-linux-gnu -- -D warnings + build: cargo +{{stable_toolchain}} build --locked @@ -31,15 +39,32 @@ test: flake-check: nix flake check +# Eval-only flake check across all supported systems (no builds) +flake-check-eval-all: + nix flake check --all-systems --no-build + # ============================================================================= # Docs # ============================================================================= docs: + #!/usr/bin/env bash + set -euo pipefail + cp CHANGELOG.md docs/src/changelog.md mdbook build docs + rm -f docs/src/changelog.md + echo "Documentation built: docs/book/" docs-serve: - cd docs && mdbook serve + #!/usr/bin/env bash + set -euo pipefail + cp CHANGELOG.md docs/src/changelog.md + trap 'rm -f docs/src/changelog.md' EXIT + (cd docs && mdbook serve --open) + +# Markdown rules and ignores live in .markdownlint-cli2.jsonc; pin the linter version. +lint-md: + npx --yes markdownlint-cli2@0.23.2 "**/*.md" # ============================================================================= # Dependency policy @@ -55,5 +80,192 @@ audit: # Aggregate # ============================================================================= -ci-rust: fmt-check clippy build test +ci-rust: fmt-check clippy clippy-release clippy-linux build test ci: ci-rust flake-check + +# ============================================================================= +# Build Matrix — Cross-platform builds with varying optimization levels +# ============================================================================= +# +# Optimization Levels: +# debug - Fast compile, no optimizations, debug symbols (for development) +# release - Cargo.toml release profile (opt-level=3, fat LTO, stripped) +# optimized - Release profile with thin LTO and one codegen unit +# max - Release profile with CPU targeting and source path remapping +# +# Targets: +# native - Current platform +# linux - x86_64-unknown-linux-gnu +# linux-musl - x86_64-unknown-linux-musl (static binary, no glibc dependency) +# linux-arm - aarch64-unknown-linux-gnu (ARM64 Linux: Graviton, Pi 4/5) +# macos - x86_64-apple-darwin (Intel Mac) +# macos-arm - aarch64-apple-darwin (Apple Silicon: M1 through M5) +# +# Usage: +# just build-matrix optimized linux # Build optimized for Linux +# just build-matrix max macos-arm # Max optimization for Apple Silicon +# just build-matrix release # Release build for current platform +# just build-all optimized # Build all platforms at optimization level +# ============================================================================= + +# Build with a specific optimization level and optional target; preserve env overrides. +build-matrix level target="native": + #!/usr/bin/env bash + set -euo pipefail + + LEVEL="{{level}}" + TARGET="{{target}}" + + # Validate optimization level + case "$LEVEL" in + debug|release|optimized|max) ;; + *) + echo "Error: Invalid optimization level '$LEVEL'" + echo "Valid levels: debug, release, optimized, max" + exit 1 + ;; + esac + + # Map target alias to Rust target triple + case "$TARGET" in + native) RUST_TARGET="" ;; + linux) RUST_TARGET="x86_64-unknown-linux-gnu" ;; + linux-musl) RUST_TARGET="x86_64-unknown-linux-musl" ;; + linux-arm) RUST_TARGET="aarch64-unknown-linux-gnu" ;; + macos) RUST_TARGET="x86_64-apple-darwin" ;; + macos-arm) RUST_TARGET="aarch64-apple-darwin" ;; + *) + echo "Error: Invalid target '$TARGET'" + echo "Valid targets: native, linux, linux-musl, linux-arm, macos, macos-arm" + exit 1 + ;; + esac + + CARGO_ARGS=(--locked) + # Set optimization defaults without replacing caller overrides. + case "$LEVEL" in + debug) + export CARGO_PROFILE_DEV_OPT_LEVEL="${CARGO_PROFILE_DEV_OPT_LEVEL:-0}" + echo "Building: debug (fast compile, no optimizations)" + ;; + release) + CARGO_ARGS+=(--release) + echo "Building: release (Cargo.toml release profile)" + ;; + optimized) + CARGO_ARGS+=(--release) + export CARGO_PROFILE_RELEASE_LTO="${CARGO_PROFILE_RELEASE_LTO:-thin}" + export CARGO_PROFILE_RELEASE_CODEGEN_UNITS="${CARGO_PROFILE_RELEASE_CODEGEN_UNITS:-1}" + echo "Building: optimized (thin LTO by default)" + ;; + max) + CARGO_ARGS+=(--release) + export CARGO_PROFILE_RELEASE_LTO="${CARGO_PROFILE_RELEASE_LTO:-fat}" + export CARGO_PROFILE_RELEASE_CODEGEN_UNITS="${CARGO_PROFILE_RELEASE_CODEGEN_UNITS:-1}" + export CARGO_PROFILE_RELEASE_OPT_LEVEL="${CARGO_PROFILE_RELEASE_OPT_LEVEL:-3}" + export CARGO_PROFILE_RELEASE_STRIP="${CARGO_PROFILE_RELEASE_STRIP:-symbols}" + # Cargo prefers encoded flags; use that format for paths containing spaces. + if [[ -n "${CARGO_ENCODED_RUSTFLAGS+x}" ]]; then + configured_flags="$CARGO_ENCODED_RUSTFLAGS" + build_flags=() + else + configured_flags="${RUSTFLAGS:-}" + IFS=$' \t\n' read -r -d '' -a build_flags < <(printf '%s\0' "$configured_flags") + fi + build_flags+=( + "--remap-path-prefix=${CARGO_HOME:-$HOME/.cargo}/registry/src=/cargo/registry" + "--remap-path-prefix=$PWD=/workspace" + ) + if [[ "$configured_flags" != *target-cpu* ]]; then + case "$TARGET" in + native) build_flags+=(-C target-cpu=native) ;; + linux|linux-musl|macos) build_flags+=(-C target-cpu=x86-64-v3) ;; + esac + fi + build_flags_encoded="$(IFS=$'\x1f'; printf '%s' "${build_flags[*]}")" + if [[ -n "${CARGO_ENCODED_RUSTFLAGS:-}" ]]; then + build_flags_encoded="$CARGO_ENCODED_RUSTFLAGS"$'\x1f'"$build_flags_encoded" + fi + export CARGO_ENCODED_RUSTFLAGS="$build_flags_encoded" + echo "Building: max (CPU targeting and source path remapping)" + ;; + esac + + HOST_TRIPLE="$(rustc +{{stable_toolchain}} -vV | awk '/^host:/ { print $2 }')" + CARGO_SUBCOMMAND=build + if [[ -n "$RUST_TARGET" ]]; then + echo "Target: $RUST_TARGET" + CARGO_ARGS+=(--target "$RUST_TARGET") + if [[ "$RUST_TARGET" != "$HOST_TRIPLE" ]]; then + if ! command -v cargo-zigbuild >/dev/null 2>&1 || ! command -v zig >/dev/null 2>&1; then + echo "Error: cross-compilation requires cargo-zigbuild and Zig on PATH." >&2 + exit 1 + fi + CARGO_SUBCOMMAND=zigbuild + fi + else + echo "Target: native ($HOST_TRIPLE)" + fi + cargo +{{stable_toolchain}} "$CARGO_SUBCOMMAND" "${CARGO_ARGS[@]}" + if [[ -n "$RUST_TARGET" ]]; then + echo "Output: target/$RUST_TARGET/$([ "$LEVEL" = "debug" ] && echo "debug" || echo "release")/postmaster" + else + echo "Output: target/$([ "$LEVEL" = "debug" ] && echo "debug" || echo "release")/postmaster" + fi + +# Build all platforms at a given optimization level (requires cross-compilation setup) +build-all level="release": + #!/usr/bin/env bash + set -euo pipefail + echo "Building all platforms at '{{level}}' optimization level..." + echo "Note: cross targets need their toolchains installed first" + echo " (e.g. 'rustup target add '); a missing toolchain fails loudly." + echo "Cross-compilation also requires cargo-zigbuild, Zig, and a macOS SDK for Darwin targets." + for target in native linux linux-musl linux-arm macos macos-arm; do + echo "" + echo "=== Building target: $target ===" + just build-matrix {{level}} "$target" + done + +# Show build matrix help +build-help: + @echo "Build Matrix — Cross-platform builds with optimization levels" + @echo "" + @echo "USAGE:" + @echo " just build-matrix [target]" + @echo "" + @echo "ARGUMENTS:" + @echo " level Required. Optimization level (see below)" + @echo " target Optional. Platform target (default: native)" + @echo "" + @echo "OPTIMIZATION LEVELS:" + @echo " debug Fast compile, no optimizations, includes debug symbols" + @echo " Best for: development, debugging, quick iteration" + @echo "" + @echo " release Cargo.toml release profile (opt-level=3, fat LTO, stripped)" + @echo "" + @echo " optimized LTO (thin) + single codegen unit" + @echo "" + @echo " max Release with CPU targeting and source path remapping" + @echo "" + @echo "TARGETS:" + @echo " native Current platform (default)" + @echo " linux x86_64-unknown-linux-gnu" + @echo " linux-musl x86_64-unknown-linux-musl (static binary)" + @echo " linux-arm aarch64-unknown-linux-gnu (ARM64: Graviton, Pi 4/5)" + @echo " macos x86_64-apple-darwin (Intel Mac)" + @echo " macos-arm aarch64-apple-darwin (Apple Silicon: M1-M5)" + @echo "" + @echo "EXAMPLES:" + @echo " just build-matrix debug # Quick dev build" + @echo " just build-matrix release # Standard release" + @echo " just build-matrix optimized linux # Optimized for Linux" + @echo " just build-matrix max macos-arm # Max for Apple Silicon" + @echo " just build-matrix max linux-arm # Max for ARM Linux" + @echo "" + @echo "OVERRIDES AND PREREQUISITES:" + @echo " Existing RUSTFLAGS / CARGO_ENCODED_RUSTFLAGS and profile overrides are preserved." + @echo " max defaults: native CPU for native, x86-64-v3 for x86 targets, baseline for ARM." + @echo " Matching host/target triples use cargo build; cross builds use cargo zigbuild." + @echo " Install the Rust target, cargo-zigbuild, and Zig before cross-compiling." + @echo " Darwin cross builds also require a macOS SDK." diff --git a/README.md b/README.md index 647ad3d..157f7dd 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,32 @@ # postmaster -**postmaster** is a standalone, format-neutral local secret -materialization engine. It decrypts encrypted secret inputs at process -launch time and injects them into a child process via environment -variables, files, or systemd credentials — then `execvp`s your binary -directly. No Node, no shell, no separate CLI process in the runtime path. +Postmaster decrypts local secret inputs at process launch and delivers values +through environment variables, files, or systemd credentials. It then replaces +the launcher with your binary through `execvp`. The first input adapter is wire-compatible with [dotenvx](https://github.com/dotenvx/dotenvx)-encrypted `.env` files (same ECIES/secp256k1 + HKDF-SHA256 + AES-256-GCM crypto path), so existing -`.env` files encrypted with the dotenvx CLI decrypt byte-exact through -postmaster's native Rust implementation. dotenvx is one adapter, not the -ceiling — the architecture supports file-based (`.env`), HashiCorp Vault, -AWS SSM, and other secret providers (1Password, etc.) as source/custody -backends. - -Postmaster works with Nix, AWS CDK, Ansible, SaltStack, Puppet, -Terraform, and OpenTofu as deployment automation targets, all sharing -the same `exec.json` contract. - -The trick that makes this compose: the ciphertext is *designed* to be -public. Every value is ECIES/secp256k1-encrypted individually, and the -embedded public key only permits encrypting *new* values. So the -world-readable Nix store — normally the reason secrets and Nix don't -mix — stops being an adversary. Encrypted env files ship inside the -closure, deploy atomically, roll back with the generation, and the -entire secret surface collapses to one 64-hex private key per -environment. +`.env` files encrypted with the dotenvx CLI decrypt through Postmaster's +native Rust implementation. Postmaster also reads encrypted +`postmaster_bundle` JSON files. External systems such as Vault, AWS SSM, +and 1Password can deliver private keys to its local key sources before launch. + +Deployment tools such as Nix, AWS CDK, Ansible, SaltStack, Puppet, Terraform, +and OpenTofu can generate the same `exec.json` contract. Postmaster doesn't +fetch secrets from those tools or remote stores. + +Encrypted values can be public: each value is ECIES/secp256k1-encrypted, +and the embedded public key permits encryption but not decryption. +Encrypted env files can ship in the Nix closure and roll back with the +generation. Keep private keys separate and protect artifact write access: +anyone with the public key can encrypt replacement values. Plaintext +passthrough entries are public too, so they must not contain secrets in a +public artifact. Runtime flow per service (systemd path): -``` +```text 1. Nix store holds the encrypted .env file (ciphertext, public) ↓ 2. systemd LoadCredential= places key material in $CREDENTIALS_DIRECTORY @@ -47,9 +43,10 @@ Runtime flow per service (systemd path): macOS runs the same flow under launchd, with a RAM disk replacing the private tmpfs. -Plaintext never touches persistent disk. Postmaster decrypts natively -and `execvp`s your binary directly from the same process -image — no Node, no separate CLI process, no shell in the startup path. +Postmaster decrypts natively and replaces the launcher with your binary. +Deployments must provide RAM-backed storage for secret files and configure +swap and dump protections. A hand-written `files` config without +`verify_ramdisk` does not establish that its directory is RAM-backed. ## CLI @@ -73,27 +70,27 @@ $ postmaster --help ## Injection modes -**`mode = "env"` (default).** Decrypted values are exported into the -process environment and the wrapper `exec`s your binary. Correct for -12-factor apps. +**`mode = "env"`.** Postmaster exports resolved values into the application +environment and replaces the launcher with your binary. **`mode = "files"`.** Values are written one-file-per-key onto a namespace-private tmpfs (`TemporaryFileSystem=/run/postmaster`; on macOS, a per-service directory on an HFS RAM disk) and only `_FILE` pointer -variables are exported — the Docker-secrets convention. Secrets are +variables are exported by default, following the Docker-secrets convention. +`passthrough` also exports selected values. File-only projected secrets are absent from environ, `ps e`, crash-dump environment sections, and ambient child inheritance. -**`mode = "credentials"`.** Real systemd credentials, served on demand by -the postmaster daemon. The consumer's unit gets +**`mode = "credentials"`.** The launcher exports pointers to credentials +that systemd has already supplied, or fetches them from configured local +Postmaster sockets. With daemon-backed systemd delivery, the consumer gets `LoadCredential=:/run/postmaster-credd//.sock` per key and the app reads `$CREDENTIALS_DIRECTORY/` from unit-private, unswappable -ramfs. Strongest hygiene of the three. +ramfs. The deployment controls credential storage and access. ## Key sources -Postmaster reads private keys from local terminal sources only — it never -fetches from remote systems: +Postmaster reads private keys from four local sources: - **systemd credentials** (`LoadCredential=`) — PID 1 places key material in `$CREDENTIALS_DIRECTORY` before postmaster starts. Includes @@ -101,22 +98,27 @@ fetches from remote systems: - **Files** — a `.env.keys`-format file on local disk (not in the Nix store) - **macOS Keychain** — key material stored as generic-password items, - read natively by postmaster via `security(1)` + read natively by postmaster via the Security.framework API - **Environment** — `DOTENV_PRIVATE_KEY*` variables in the process - environment (set by the service manager) + environment (set by the service manager); bundle configs use + `POSTMASTER_KEY` instead ## Integration Postmaster is the local secret materialization stage in a 5-stage pipeline: custody (Vault/SSM/1Password/TPM2) → rendering (Nix/Terraform/ CDK/Ansible/Salt/Puppet) → delivery (credentials/files/keychain/env) → -materialization (postmaster) → launch (execvp). Each stage is owned by a -different system; postmaster owns exactly materialization. +materialization (postmaster) → launch (execvp). Each stage has a separate +responsibility. Postmaster handles local materialization and the handoff to +the target process. The +stage-by-stage breakdown lives in +[The secret pipeline](docs/src/architecture/postmaster.md#the-secret-pipeline). The `exec.json` contract and `postmaster exec --check` conformance suite are the interface between postmaster and every integration. An -integration is correct if and only if the `exec.json` it emits passes -`--check` and the conformance suite. +integration must emit configs accepted by `--check` and verify its launch +behavior against the conformance suite. Host permissions, key availability, +and service-manager wiring need separate validation. ## Documentation @@ -124,7 +126,7 @@ Full documentation is in the [docs/](docs/) directory, buildable with [mdBook](https://rust-lang.github.io/mdBook/): ```console -$ mdbook serve docs +$ just docs-serve ``` See [docs/src/SUMMARY.md](docs/src/SUMMARY.md) for the table of contents. @@ -132,12 +134,22 @@ See [docs/src/SUMMARY.md](docs/src/SUMMARY.md) for the table of contents. ## Building ```console -$ cargo build -$ cargo test -$ cargo clippy --all-targets -$ cargo fmt --check +$ just build # debug build +$ just test # run tests +$ just clippy # lint +$ just fmt-check # format check +$ just ci-rust # all of the above in one command +$ just build-matrix max macos-arm # optimized release ``` +Source builds require Rust 1.99.1 or newer. `just build-help` lists the +optimization levels and cross-compilation targets. + +Cross builds use `cargo zigbuild` and require the Rust target, `cargo-zigbuild`, +and Zig to be installed; Darwin cross builds also require a macOS SDK. +The matrix preserves compiler flags and profile environment overrides. Its +`max` level remaps checkout and Cargo registry source paths in build outputs. + With Nix: ```console @@ -145,6 +157,10 @@ $ nix build $ nix flake check ``` +The flake exports packages and an overlay. Service-manager bindings live in +deployment integrations; they must render `exec.json` and configure storage, +permissions, cleanup, and hardening. + ## License MIT diff --git a/deny.toml b/deny.toml index 4672a7f..ba0d9aa 100644 --- a/deny.toml +++ b/deny.toml @@ -1,4 +1,4 @@ -# cargo-deny configuration for envelope / postmaster. +# cargo-deny configuration for postmaster. # https://embarkstudios.github.io/cargo-deny/ [graph] @@ -39,3 +39,20 @@ confidence-threshold = 0.93 # The postmaster crate is the only member today. [licenses.private] ignore = true + +[sources] +unknown-git = "deny" + +[bans] +# Warn on duplicate crate versions — companion to clippy's +# multiple_crate_versions (crate-level; allowed at the crate root for +# exactly the case skipped below, since that lint has no per-package +# scoping). New duplicates should fail review, not land quietly. +multiple-versions = "warn" + +# syn 2 + syn 3 coexist ONLY because wasm-bindgen (target-gated to +# wasm32-unknown-unknown inside the ecies dep, never compiled for +# postmaster's real targets) pins syn 2 while serde_derive uses syn 3 — +# uncontrollable until upstream wasm-bindgen moves. Remove this skip, and +# the crate-root allow in src/lib.rs, when the tree converges. +skip = [{ name = "syn" }] diff --git a/docs/examples/exec-bundle.json b/docs/examples/exec-bundle.json new file mode 100644 index 0000000..29383cf --- /dev/null +++ b/docs/examples/exec-bundle.json @@ -0,0 +1,11 @@ +{ + "mode": "env", + "keys": [ + "environment" + ], + "bundle_files": [ + "/nix/store/example-postmaster-bundle-myapp/secrets.postmaster.bundle.json" + ], + "strict": true, + "overload": false +} diff --git a/docs/examples/exec-credentials-darwin.json b/docs/examples/exec-credentials-darwin.json index afd8af0..5bb46ab 100644 --- a/docs/examples/exec-credentials-darwin.json +++ b/docs/examples/exec-credentials-darwin.json @@ -4,10 +4,10 @@ "DATABASE_URL", "REDIS_URL" ], - "secrets_dir": "/private/var/run/dotenvx/myapp", + "secrets_dir": "/private/var/run/postmaster/myapp", "sockets": { - "DATABASE_URL": "/private/var/run/dotenvx-credd/myapp/DATABASE_URL.sock", - "REDIS_URL": "/private/var/run/dotenvx-credd/myapp/REDIS_URL.sock" + "DATABASE_URL": "/private/var/run/postmaster-credd/myapp/DATABASE_URL.sock", + "REDIS_URL": "/private/var/run/postmaster-credd/myapp/REDIS_URL.sock" }, - "verify_ramdisk": "/private/var/run/dotenvx" + "verify_ramdisk": "/private/var/run/postmaster" } diff --git a/docs/examples/exec-env.json b/docs/examples/exec-env.json index 0c99dd6..4accaa1 100644 --- a/docs/examples/exec-env.json +++ b/docs/examples/exec-env.json @@ -2,12 +2,12 @@ "mode": "env", "keys": [ { - "credential": "dotenvx-myapp" + "credential": "postmaster-myapp" }, "environment" ], "env_files": [ - "/nix/store/example-dotenvx-env-myapp/.env.production" + "/nix/store/example-postmaster-env-myapp/.env.production" ], "strict": true, "overload": false diff --git a/docs/examples/exec-files.json b/docs/examples/exec-files.json index 73bf56e..5f0c64c 100644 --- a/docs/examples/exec-files.json +++ b/docs/examples/exec-files.json @@ -2,15 +2,15 @@ "mode": "files", "keys": [ { - "file": "/run/envelope/myapp.env.keys" + "file": "/var/lib/postmaster/myapp.env.keys" } ], "env_files": [ - "/nix/store/example-dotenvx-env-myapp/.env.production" + "/nix/store/example-postmaster-env-myapp/.env.production" ], "strict": true, "overload": false, - "secrets_dir": "/run/dotenvx/myapp", + "secrets_dir": "/run/postmaster/myapp", "passthrough": [ "RUST_LOG" ] diff --git a/docs/schema/exec.schema.json b/docs/schema/exec.schema.json index cefc76e..573d32b 100644 --- a/docs/schema/exec.schema.json +++ b/docs/schema/exec.schema.json @@ -1,8 +1,8 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://github.com/beardedeagle/envelope/docs/schema/exec.schema.json", + "$id": "https://github.com/beardedeagle/postmaster/docs/schema/exec.schema.json", "title": "postmaster exec.json", - "description": "Public launcher configuration for the current dotenvx-shaped postmaster materialization ABI instance.", + "description": "Public Postmaster launch configuration: local inputs, key sources, and projection settings.", "type": "object", "additionalProperties": false, "required": ["mode"], @@ -25,6 +25,13 @@ "type": "string" } }, + "bundle_files": { + "type": "array", + "default": [], + "items": { + "type": "string" + } + }, "strict": { "type": "boolean", "default": true @@ -73,16 +80,25 @@ "required": ["mode"] }, "then": { - "required": ["keys", "env_files"], + "required": ["keys"], "properties": { "keys": { "minItems": 1 }, - "env_files": { "minItems": 1 }, "secrets_dir": { "const": null }, "credential_keys": { "maxItems": 0 }, "sockets": { "maxProperties": 0 }, "verify_ramdisk": { "const": null }, "passthrough": { "maxItems": 0 } - } + }, + "anyOf": [ + { + "required": ["env_files"], + "properties": { "env_files": { "minItems": 1 } } + }, + { + "required": ["bundle_files"], + "properties": { "bundle_files": { "minItems": 1 } } + } + ] } }, { @@ -91,14 +107,23 @@ "required": ["mode"] }, "then": { - "required": ["keys", "env_files", "secrets_dir"], + "required": ["keys", "secrets_dir"], "properties": { "keys": { "minItems": 1 }, - "env_files": { "minItems": 1 }, "secrets_dir": { "type": "string" }, "credential_keys": { "maxItems": 0 }, "sockets": { "maxProperties": 0 } - } + }, + "anyOf": [ + { + "required": ["env_files"], + "properties": { "env_files": { "minItems": 1 } } + }, + { + "required": ["bundle_files"], + "properties": { "bundle_files": { "minItems": 1 } } + } + ] } }, { @@ -112,6 +137,7 @@ "credential_keys": { "minItems": 1 }, "keys": { "maxItems": 0 }, "env_files": { "maxItems": 0 }, + "bundle_files": { "maxItems": 0 }, "overload": { "const": false }, "passthrough": { "maxItems": 0 } } diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 747c265..37fe6ec 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -2,6 +2,8 @@ [Introduction](./introduction.md) +[Executive overview](./executive-overview.md) + # Getting Started - [Quick start](./getting-started/quick-start.md) @@ -14,6 +16,15 @@ - [Materialization ABI](./architecture/materialization-abi.md) - [Threat model](./architecture/threat-model.md) +# Unsafe Code + +- [Overview](./unsafe-code/index.md) +- [Signal deferral](./unsafe-code/signal-deferral.md) +- [Sibling launch monitor](./unsafe-code/monitor.md) +- [macOS libc boundary](./unsafe-code/macos-libc-boundary.md) +- [systemd fd ownership (Linux)](./unsafe-code/systemd-fd-ownership.md) +- [Test-only env mutation](./unsafe-code/test-env-mutation.md) + # Reference - [CLI reference](./reference/cli.md) diff --git a/docs/src/architecture/materialization-abi.md b/docs/src/architecture/materialization-abi.md index 6b74ddd..f93ad0b 100644 --- a/docs/src/architecture/materialization-abi.md +++ b/docs/src/architecture/materialization-abi.md @@ -4,20 +4,18 @@ contract between public deployment artifacts, local private key material, and the process that receives plaintext at runtime. -## Audience Quickstart (Plain Language) +## Audience quickstart -**What this is:** the contract that every integration (Nix, Terraform, -CDK, Ansible, etc.) must follow when wiring postmaster. If you're writing -a binding or evaluating whether a generated config is correct, this is -your page. +Deployment integrations generate local inputs for Postmaster. This contract +defines those inputs, key sources, resolution rules, and output projections. ### Who this is for | Reader | What to take | | -------- | ------------ | | Integration author | The entire page — this is your contract | -| Security engineer | "Non-goals" and "Resolution" — what postmaster will never do | -| New user | "Current ABI instance" and the exec.json example — the 60-second tour | +| Security engineer | "Non-goals" and "Resolution" | +| New user | "Current ABI instance" and the exec.json example | | Platform / SRE | "Key sources" and "Validation" — what the host needs | ### Quick glossary @@ -25,7 +23,7 @@ your page. | Term | Plain meaning | | ------ | --------------- | | **ABI** | Application Binary Interface — the contract between config files, key material, and the launcher | -| **exec.json** | A JSON file that tells postmaster what to decrypt, how to inject, and what to launch | +| **exec.json** | A JSON file that selects inputs, key sources, and projection mode. The launch command is supplied separately after `--`. | | **Projection** | Where decrypted secrets go — env vars, files, or systemd credentials | | **Adapter** | An input format (.env, postmaster_bundle) — postmaster supports multiple, not just one | @@ -35,11 +33,11 @@ The ABI is deliberately local: - private key material arrives through local terminal sources - `postmaster` decrypts and projects plaintext on the host - plaintext is handed to the target process through one selected projection -- failure happens before `exec`, not after a partially configured launch +- required validation and decryption checks finish before `exec` This page describes the ABI and how `exec.json` fits inside it. It is a -contract for bindings and documentation recipes, not an invitation to put -provider clients into `postmaster`. +contract for bindings and documentation recipes. Remote provider clients +belong in the delivery tooling, outside `postmaster`. ## Non-goals @@ -63,11 +61,11 @@ The ABI has five layers. ```mermaid flowchart TD - art["1. Artifact descriptors\nidentify encrypted local inputs"] - key["2. Key-source descriptors\nidentify local private key material"] - res["3. Resolution rules\nturn encrypted entries into plaintext"] - proj["4. Projection policy\ndecides where bytes appear"] - launch["5. Launch semantics\nexecvp replaces postmaster with target"] + art["(1) Artifact descriptors
identify encrypted local inputs"] + key["(2) Key-source descriptors
identify local private key material"] + res["(3) Resolution rules
turn encrypted entries into plaintext"] + proj["(4) Projection policy
decides where bytes appear"] + launch["(5) Launch semantics
execvp replaces postmaster with target"] art --> res key --> res @@ -91,9 +89,9 @@ private keys are never config fields. `exec.json` is the first ABI instance. It is implicitly: - ABI version: `0` -- input adapter: `.env` (wire-compatible with dotenvx-encrypted files) -- artifact shape: `env_files` -- key material shape: `.env.keys` / `DOTENV_PRIVATE_KEY*` +- input adapters: `.env` and `postmaster_bundle` +- artifact fields: `env_files` and `bundle_files` +- key variables: `DOTENV_PRIVATE_KEY*` for dotenv, `POSTMASTER_KEY` for bundles - projection modes: `env`, `files`, and `credentials` The current parser does not accept explicit `version` or `adapter` fields. @@ -120,15 +118,17 @@ filename selects the private key variable: - `.env` maps to `DOTENV_PRIVATE_KEY` - `.env.production` maps to `DOTENV_PRIVATE_KEY_PRODUCTION` -- non-alphanumeric environment suffix bytes normalize to `_` +- environment names must be non-empty `[A-Za-z0-9_]` (letters fold to + upper case); anything else is rejected -The `.env` adapter is the first adapter, not the ceiling of the system. +The bundle adapter below provides another input format under the same +projection contract. ## Neutral bundle adapter -The `postmaster_bundle` adapter is a second input format, not a replacement -for `.env`. Its job is to let non-`.env` ecosystems produce a public -encrypted artifact without pretending their native model is an `.env` file. +The `postmaster_bundle` adapter reads structured JSON artifacts alongside +dotenv inputs. Producers can represent binary and UTF-8 entries without +encoding their native data model as a dotenv file. The on-disk format is a JSON container. JSON keeps generated artifacts easy for Terraform, OpenTofu, CDK, Ansible, Salt, Puppet, and Nix to render and @@ -139,7 +139,7 @@ diff, while encrypted values remain opaque base64 strings. "format": "postmaster.bundle", "version": 1, "profile": "production", - "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm", + "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm-entry-aad", "recipients": [ { "id": "host:api-01", @@ -160,10 +160,21 @@ diff, while encrypted values remain opaque base64 strings. ``` All fields above are public metadata except `ciphertext`, which is encrypted -and authenticated. The metadata that affects interpretation must be covered -by authentication so a store or repo adversary cannot rename a key, change a -profile, change a recipient id, switch an encoding, or replay a value between -profiles without detection. +and authenticated. Each entry's ciphertext is additionally bound to its key +name as AES-GCM additional authenticated data (the `-entry-aad` suite): a +store or repo adversary who cuts a ciphertext from one entry and pastes it +under another key name gets an authentication failure at decryption, not a +mislabeled secret. + +The decoded envelope is a 65-byte uncompressed secp256k1 ephemeral public key, +a 16-byte nonce, a 16-byte authentication tag, then ciphertext. HKDF-SHA256 +uses the uncompressed ephemeral and shared points, matching `ecies` defaults. +The entry name's exact UTF-8 bytes are the AAD; plaintext is returned only +after AES-256-GCM authentication succeeds. + +The remaining metadata, including profile, recipient IDs, and encodings, is +not cryptographically bound. A format that authenticates those fields would +need canonical serialized bytes for reproducible builds and stable vectors. The design constraints are: @@ -171,17 +182,19 @@ The design constraints are: values. - `suite` is mandatory so cryptographic suites can be explicit rather than inferred from payload length. -- `profile` is optional public selection metadata; it is not a secret. -- `recipients[*].id` is public routing metadata used to select local private - key material. +- `profile` and `recipients` are public metadata. They are parsed but do not + select local private keys or filter entries. +- Private key material comes from the `POSTMASTER_KEY` variable: + comma-separated rotation candidates are admitted, and + `POSTMASTER_KEY_` variants match by the same predicate as + `DOTENV_PRIVATE_KEY_*`. There is no per-environment filename mapping — + bindings select bundle paths through `bundle_files`. - `entries` keys must use the same identifier rule as `.env`-derived keys: `[A-Za-z_][A-Za-z0-9_]*`. -- `encoding` is either `utf8` or `bytes`. `env` projection rejects bytes that - cannot become a POSIX environment value; `files` and `credentials` preserve - byte-exact values. -- The canonical serialized bytes for authenticated metadata must be specified - before implementation. Generated artifacts need deterministic bytes for - reproducible builds and stable test vectors. +- `encoding` is either `utf8` or `bytes`. A `utf8` entry must decrypt to valid + UTF-8. Env projection rejects NUL bytes; files preserve byte-exact values. +- Bundles are accepted in `env` and `files` modes. The credential daemon + resolves dotenv entries; `credentials` mode does not accept `bundle_files`. - A bundle can contain many entries for one projection, but it does not encode service-manager policy. Projection remains in the `postmaster` config, not inside the encrypted artifact. @@ -193,13 +206,11 @@ launch, and the same output projection semantics as `.env` values. The implementation ships with conformance vectors for: - minimal valid bundle -- multiple recipients -- binary value projected to files - invalid key name - unknown version -- tampered authenticated metadata +- tampered `format`/`version`/`suite` values (fail-closed parsing) - wrong local private key -- replayed ciphertext under a different entry name or profile +- replayed ciphertext under a different entry name ## Key sources @@ -211,8 +222,8 @@ Implemented launcher key sources are local and terminal: - `{"file": "/path/to/.env.keys"}` reads a local file and fails closed if the file is unavailable or under `/nix/store`. - `{"keychain": ""}` reads from macOS Keychain and is terminal. -- `"environment"` reads `DOTENV_PRIVATE_KEY*` from the process environment - and is terminal. +- `"environment"` reads the required adapters' private-key variables from the + process environment and is terminal. Provider names such as `aws_ssm` and `vault` are reserved contract language, but they are not implemented key sources. A Vault Agent, cloud-init step, @@ -225,7 +236,7 @@ local sources. Resolution must: - parse every configured encrypted artifact before launching the target -- build the wanted private-key set from artifact metadata +- build the wanted private-key set from configured artifact names and formats - load key material from the ordered local sources - decrypt with the selected adapter - reject malformed key names @@ -237,6 +248,10 @@ Resolution must: For the `.env` adapter, this is implemented by `resolve_all` and the same native ECIES path used by the credential daemon. +`strict: false` permits undecryptable dotenv values to be logged and omitted. +`--verify-keys` rejects those omissions. Bundle authentication always fails +closed, independent of `strict`. + ## Diagnostics and redaction Failures identify the field, artifact, key name, or projection that failed @@ -265,9 +280,12 @@ because POSIX environment variables cannot carry them safely. Each resolved value is written as a `0600` file under `secrets_dir`. `postmaster` exports `_FILE` pointers for each secret. +The deployment must supply RAM-backed storage. The launcher does not establish +RAM backing when `verify_ramdisk` is absent. + The launcher refuses to follow symlinks when writing secret files. On macOS, -when `verify_ramdisk` is set, it verifies the configured mount before writing -plaintext. +when `verify_ramdisk` is set, it verifies the configured mount and the opened +directory's device and ownership before writing plaintext. `passthrough` may additionally export selected keys as real environment variables. Passthrough values containing NUL bytes are rejected. @@ -277,9 +295,10 @@ variables. Passthrough values containing NUL bytes are rejected. On systemd, PID 1 has already materialized credentials and the launcher only exports `_FILE` pointers into `$CREDENTIALS_DIRECTORY`. -On launchd, the launcher can fetch configured keys from local postmaster -sockets, write them into the verified RAM disk directory, and export -credential-style pointers. +When `sockets` is configured, the launcher fetches values from local +Postmaster sockets, writes them beneath `secrets_dir`, and exports +credential-style pointers. This path is normally used with launchd. RAM +backing is verified only when `verify_ramdisk` is set on macOS. Every `credential_keys` entry must be a valid identifier before any fetch or write occurs. @@ -310,19 +329,20 @@ the key file is missing, the keychain item is absent, or the credential source is not provisioned. The launcher's fail-closed behavior is the runtime guarantee; `--check` cannot substitute for it. -`postmaster setup --config --recheck` provides runtime -environment verification — it probes the filesystem and keychain to -confirm that key material is actually accessible at the configured paths, -without decrypting any secrets. It complements `--check`: run `--check` -in CI for config correctness, run `setup --recheck` on the host for -environment readiness. +`postmaster setup --config --recheck` checks local provisioning +without decrypting secrets. File sources receive descriptor-based ownership, +permission, and macOS ACL checks. Credential sources receive path-presence and +regular-file checks. Keychain checks look for the required items; environment +checks look for required variables. These checks do not prove that the keys +can decrypt the configured inputs. Run `--check` in CI for config shape and +`setup --recheck` on the host for provisioning checks. The full `postmaster setup` command goes beyond verification: it creates the keys directory with 0700 permissions, verifies or creates -keys files with 0600, optionally seeds keychain items (macOS, interactive), -and validates platform prerequisites. It is idempotent — each step checks -whether the target state is already present and correct, and skips if it -is. Flags: `--recheck` (verification only), `--unattended` (non-interactive, +key files with owner-only permissions, and optionally seeds macOS Keychain +items interactively. It derives a unique required-account list in first-seen +input order. Steps already satisfied are skipped. +Flags: `--recheck` (verification only), `--unattended` (non-interactive, fail closed), `--force` (re-create/re-seed), `--keys-dir ` (override default path). diff --git a/docs/src/architecture/postmaster.md b/docs/src/architecture/postmaster.md index df27dbe..2d25267 100644 --- a/docs/src/architecture/postmaster.md +++ b/docs/src/architecture/postmaster.md @@ -1,18 +1,16 @@ # postmaster: the secret materialization engine -Postmaster is a standalone Rust binary that does exactly one thing: -decrypt encrypted secret inputs at process launch time and inject -them into a child process, then replace its own process image with -the target binary via `execvp`. +Postmaster is a standalone Rust binary that decrypts secret inputs +at process launch, injects them into the child process, and replaces +its own process image with the target binary via `execvp`. -It is not a library. It is not a plugin host. It is not a daemon -framework. It is a single binary with a fixed, local, offline -contract. +It ships as a standalone binary with a local, offline contract. Decryption +and projection are implemented in the repository's Rust library crate. -## Audience Quickstart (Plain Language) +## Audience quickstart -**What this is:** the architecture of postmaster — what it does, -what it owns, and where it fits in the secret delivery pipeline. +This page describes Postmaster's runtime responsibilities and the deployment +stages around it. ### Who this is for @@ -22,7 +20,7 @@ what it owns, and where it fits in the secret delivery pipeline. | Platform / SRE | "Implementation" and "Dependency policy" — what you're deploying | | Security engineer | The entire page — this defines the security boundary | | Integration author | "What postmaster does NOT own" and the [Launcher contract](../reference/launcher-contract.md) | -| Product / project manager | "What postmaster owns" and the pipeline diagram — the 30-second summary | +| Product / project manager | "What postmaster owns" and the pipeline diagram | ### Quick glossary @@ -67,10 +65,9 @@ plaintext in its environment or files": seeds keychain items (macOS), and validates the environment — idempotently. -## What postmaster does NOT own +## What Postmaster does not own -Postmaster does NOT own anything that happens before the encrypted -artifact exists or after the child process starts: +Deployment tooling owns authoring, custody, and service-manager policy: - **Secret authoring.** Encrypting secrets is done by workstation tooling (dotenvx CLI, or any tool producing the same ECIES @@ -88,10 +85,14 @@ artifact exists or after the child process starts: SaltStack, Puppet — these tools render the deployment artifacts and wire the service manager. Postmaster does not deploy. -- **Service supervision.** Postmaster does not supervise the child - process. The service manager (systemd on Linux, launchd on macOS) - starts, monitors, and stops the service. Postmaster's job is done - the moment `execvp` fires. +- **Service supervision policy.** Postmaster owns no lifecycle policy + — no restarts, no health checks. The service manager (systemd on + Linux, launchd on macOS) starts, monitors, and stops the service. + Postmaster runs a sibling monitor alongside + the exec'd service: it forwards stop signals, escalates to SIGKILL + after a bounded grace, and removes plaintext secret files on every + death path while the monitor survives. Integration cleanup and storage + teardown provide backstops if it doesn't. - **Child behavior.** What the child process does with its secrets — reading from environment variables, files, or credentials — is the @@ -101,25 +102,26 @@ artifact exists or after the child process starts: ## The secret pipeline -The full secret lifecycle is a pipeline of distinct stages, each -owned by a different system. Postmaster owns exactly one stage. +The secret lifecycle has separate custody, rendering, delivery, +materialization, and launch responsibilities. Postmaster handles +materialization and the process handoff. ```mermaid flowchart LR subgraph s1["1. Custody"] - vault["Vault / SSM /\n1Password / TPM2"] + vault["Vault / SSM /
1Password / TPM2"] end subgraph s2["2. Rendering"] - nix["Nix / Terraform /\nCDK / Ansible"] + nix["Nix / Terraform /
CDK / Ansible"] end subgraph s3["3. Delivery"] - cred["systemd cred /\nfile / keychain"] + cred["systemd cred /
file / keychain"] end subgraph s4["4. Materialization"] - pm["postmaster\ndecrypt + inject"] + pm["postmaster
decrypt + inject"] end subgraph s5["5. Launch"] - exec["execvp\nchild = MainPID"] + exec["execvp
child = MainPID"] end vault --> nix @@ -180,7 +182,7 @@ How key material reaches postmaster at runtime. - **Files** — a `.env.keys`-format file on local disk (not in the Nix store) - **macOS Keychain** — key material stored as generic-password items, - read natively by postmaster via `security(1)` + read natively by postmaster via the Security.framework API - **Environment** — `DOTENV_PRIVATE_KEY*` variables in the process environment (set by the service manager) @@ -189,39 +191,53 @@ remote systems. ### Stage 4: Materialization (postmaster) -Postmaster decrypts encrypted inputs and injects them into the child -context. This is the only stage postmaster owns. +Postmaster decrypts local inputs and projects the resulting values into the +application's environment or files. - Decrypts `.env` files via the `ecies` crate (native Rust, offline) -- Decrypts `postmaster_bundle` files via the same crypto path +- Decrypts `postmaster_bundle` entries with name-bound AES-GCM AAD - Injects via `env`, `files`, or `credentials` mode -- Zeroizes decrypted values and private keys before `execvp` -- Fails closed if any value cannot decrypt +- Zeroizes its key ring and resolved buffers before `execvp` +- Rejects decryption failures by default; `strict: false` permits skipped + dotenv values, while bundle authentication remains mandatory ### Stage 5: Launch (execvp) -Postmaster calls `execvp`. The process image is replaced. The child -binary IS `MainPID`. Postmaster is gone. +Postmaster forks a **sibling monitor** and then calls `execvp` in the +parent. The service binary remains `MainPID`; the launcher's process image +is gone. + +The fork-child becomes the monitor. It scrubs its projected environment +pairs, keeps the termination signals blocked for life, and +supervises its parent — forwards stop signals with a 250 ms grace +before SIGKILL escalation, and removes the plaintext secret files on +every service-death path (natural exit, `kill -9`, crash), then exits. +One monitor process runs for the service's lifetime. It watches liveness +with pidfd and `poll` on Linux, or kqueue `NOTE_EXIT` on macOS. + +The monitor retains the original process environment, which can contain +private keys supplied through environment variables. Use a non-environment +key source to avoid this exposure. The credential daemon is a separate, +long-lived process that retains its key ring for requests. The service manager (systemd/launchd) supervises the child from this point. `ExecStopPost` runs `postmaster cleanup` to remove plaintext -files after the child exits (Linux). The ramdisk is destroyed when -the launchd job stops (macOS). +files after the child exits (Linux) — now a backstop behind the +monitor. The ramdisk is destroyed when the launchd job stops (macOS). ## Implementation -`postmaster/` contains a dependency-lean Rust binary (edition -2024; pure-Rust crypto, no openssl; no async runtime; syscalls via -rustix's `linux_raw` backend rather than libc FFI on Linux, leaving -one `unsafe` block for the fd-ownership assertion at the systemd -socket-activation boundary; on macOS, `libc` is used for `getpeereid` -and `PT_DENY_ATTACH` hardening — each `unsafe` site carries a SAFETY -comment) that materializes decrypted secret values as systemd -`LoadCredential=` AF_UNIX sources or directly injects them via -`execvp`. systemd's documented contract for socket credential sources +Postmaster uses Rust edition 2024, RustCrypto, and no async runtime or OpenSSL. +Linux uses rustix's `linux_raw` backend, with a libc call for `fork`. +macOS uses libc for peer checks, signal handling, kqueue, and anti-debug +hardening. Each unsafe site has a SAFETY comment and an entry in the +[unsafe-code registry](../unsafe-code/index.md). + +The binary serves decrypted values as systemd `LoadCredential=` AF_UNIX +sources or projects them before `execvp`. systemd's contract for socket sources is minimal — the manager connects once at process invocation and reads until EOF, with no request metadata in-band — so the request is encoded -in the *path*: one socket per (service, key). The module generates a +in the *path*: one socket per (service, key). A binding can generate a single `postmaster-credd.socket` unit carrying N `ListenStream=` entries; postmaster maps each inherited fd back to its path via `getsockname(2)`. @@ -234,7 +250,7 @@ is `cfg`-gated (`SO_PEERCRED`→`getpeereid`, `prctl`/`mlockall`→core-limit + `PT_DENY_ATTACH`). The binary has five entry points: the default daemon (`--bind`/ -socket-activated `serve`), `fetch` (the darwin fetch client), `exec` +socket-activated `serve`), `fetch` (the local socket client), `exec` (decrypt + inject + `execvp`), `setup` (idempotent environment verification and key provisioning), and `cleanup` (plaintext file removal for `ExecStopPost`). Its config schema, key-source precedence, @@ -243,21 +259,36 @@ and per-mode injection rules are the cross-binding contract at ## Dependency policy -Postmaster has 8 dependencies: +Source builds require Rust 1.99.1 or newer. The flake exports packages and +an overlay, not NixOS or nix-darwin service modules. Deployment integrations +own the service units, RAM-backed storage, and hardening described above. + +The runtime dependencies are: - `ecies` — crypto (secp256k1 + AES-256-GCM) -- `dotenvy` — `.env` file parser +- `aes-gcm` — bundle-envelope authentication with entry-name AAD +- `dotenvy` — private-key file parsing - `serde` + `serde_json` — JSON config deserialization - `base64` — ciphertext decoding - `hex` — key parsing -- `rustix` — syscalls (no libc FFI on Linux) -- `libc` — macOS only (for `getpeereid` and `PT_DENY_ATTACH`) +- `sha2` — SHA-256 authorization of daemon source bytes +- `getrandom` — random names for private temporary files +- `rustix` — syscalls (raw syscalls via `linux_raw` on Linux, incl. the + monitor's pidfd/poll and the experimental `runtime` signal-mask API; + the only libc FFI on Linux is `fork(2)` — see the unsafe registry) +- `libc` — macOS (getpeereid, `PT_DENY_ATTACH`, the monitor's + kqueue/signal ops) plus Linux `fork(2)` only (rustix has no fork + wrapper) +- `security-framework` — macOS only (Security.framework keychain reads) - `zeroize` — secret memory wiping -No CLI parsing library (clap, etc.). No async runtime. No OpenSSL. -No network client. No plugin system. The dependency set is -intentionally minimal: smaller binary, smaller attack surface, -faster startup, fewer supply-chain risks. +Bundle envelopes use Postmaster's AAD decoder with the released `ecies` +curve/HKDF helpers and RustCrypto AES-GCM. This preserves existing ciphertext +compatibility without an upstream AAD API dependency. + +The CLI parser uses the standard library. There is no async runtime, OpenSSL +dependency, remote secret-store client, or plugin system. Each dependency +must justify its role in the runtime path. New dependencies are rejected unless they are strictly necessary for the core decrypt-inject-execvp path and cannot be implemented in diff --git a/docs/src/architecture/threat-model.md b/docs/src/architecture/threat-model.md index eee1e7f..220dc4d 100644 --- a/docs/src/architecture/threat-model.md +++ b/docs/src/architecture/threat-model.md @@ -1,9 +1,9 @@ # Threat model -## Audience Quickstart (Plain Language) +## Audience quickstart -**What this is:** what postmaster protects, what it cannot prevent, -and why it's built this way. This is the security reference. +This reference defines Postmaster's trust boundary, deployment requirements, +and remaining exposure. ### Who this is for @@ -12,15 +12,15 @@ and why it's built this way. This is the security reference. | Security engineer | The entire page — every claim is about the security boundary | | Platform / SRE | "Swap and core dumps" and "Hardening inheritance" — what to configure | | Integration author | "Why a native launcher" — understand the design constraints | -| New user | "Secrets at rest" and "Fail-closed" — the 30-second security summary | -| Product / project manager | The residuals table — what postmaster does NOT protect against | +| New user | "Secrets at rest" and "Fail-closed" | +| Product / project manager | The residuals table | ### Quick glossary | Term | Plain meaning | | ------ | --------------- | -| **execvp** | Replaces the current process — no parent holds secrets after launch | -| **Fail-closed** | If anything fails, the service does NOT start — no partial secrets | +| **execvp** | Replaces the launcher with the target binary while keeping its PID. The sibling monitor is a separate process. | +| **Fail-closed** | A failed required check prevents launch; dotenv decryption is strict by default | | **Zeroize** | Overwrite secret memory with zeros before it's freed | | **mlockall** | Pin memory in RAM so the kernel can't swap it to disk | | **TOCTOU** | Time-of-check to time-of-use — a race between verifying and using a file | @@ -32,21 +32,21 @@ and why it's built this way. This is the security reference. | Category | Status | | -------- | ------ | | Secrets at rest (ciphertext in git/Nix store) | Safe — ciphertext is public | -| Plaintext on persistent disk | Prevented — only RAM-backed filesystems | +| Plaintext on persistent disk | Avoided when the deployment supplies RAM-backed secret storage | | Plaintext in swap | Mitigated — mlockall + MemorySwapMax=0 | | Core dumps | Mitigated — PR_SET_DUMPABLE=0, RLIMIT_CORE=0 | -| Shell injection | Prevented — no shell anywhere in the path | +| Shell injection through secret values | Values are passed without shell evaluation | | Symlink attacks on key files | Prevented — O_NOFOLLOW + fstat | | Same-UID env var exposure (env mode) | Residual — use files or credentials mode | -| Root on the host | Residual — root is always game over | +| Root on the host | Outside the trust boundary; privileged processes can inspect memory | | VM/hypervisor inspection | Residual — outside the trust boundary | -| CPU cache/register residue | Non-goal — no mitigation available | +| CPU cache/register residue | Outside Postmaster's memory-wiping guarantees | ## Why a native launcher, not a shell wrapper -Postmaster is a native Rust binary, not a shell wrapper around an -external CLI. This decision is driven by three security properties that -a shell-based approach cannot provide. +Postmaster decrypts in Rust and replaces the launcher with the service. +The relevant properties are process identity, value handling, and local +decryption. ### Process identity: execvp, not spawn @@ -55,12 +55,12 @@ call that replaces the current process image with the target binary. The process ID (PID) does not change. The service binary is `MainPID` from its first instruction. -A shell wrapper or Node.js parent process would `spawn` a child -instead. The parent stays alive as `MainPID`, which breaks: +A wrapper that spawns the service and remains alive keeps another process +in the service unit. That affects: - **systemd readiness notifications** (`Type=notify`, `sd_notify`): - systemd expects `MainPID` to send `READY=1`. A parent process that - spawns the real service means the wrong process is notifying. + notifications must come from the process the unit is configured to accept. + Keeping the wrapper as `MainPID` can leave the service outside that rule. - **Cgroup memory accounting**: the parent's memory (including private key material) is counted against the service unit's cgroup. - **Secret lifetime**: the parent process holds private keys and @@ -70,16 +70,28 @@ instead. The parent stays alive as `MainPID`, which breaks: ### No shell interpolation -A shell-based launcher would use `eval` or source-based injection to -set environment variables. That leaves `$(…)` and backticks live -inside double quotes. Combined with a public key embedded in the -repository (which lets any repo writer add or replace encrypted -values), this would be remote code execution at service start for -anyone who can commit to the repo. +A launcher that evaluates secret values through a shell can execute `$(…)` +or backticks inside those values. Anyone with the public key can encrypt a +replacement value, so artifact write access combined with shell evaluation +can become command execution at service start. -Postmaster never shells out or evals. Decrypted values move directly -into the child's environment array or a file write. No shell sits -between decryption and injection to reinterpret the values. +Postmaster doesn't evaluate secret values as shell code. Decrypted values +move directly into the application's environment array or a file write. + +### Private-key environment variables + +Postmaster removes private-key variables from the launched application's +environment in every projection mode. Both adapter namespaces are reserved: +`DOTENV_PRIVATE_KEY`, `POSTMASTER_KEY`, and their `_` variants. +The environment source can still use these variables to decrypt inputs; +ordinary inherited variables remain available to the application. + +This filtering does not erase the launcher's original environment or the +copy inherited by its sibling monitor. Prefer a non-environment key source +to avoid that exposure. Filtering also does not prevent an application from +reading key files or keychain items its OS identity can access. Keeping a +master key inaccessible to the service requires a separate OS access +boundary, such as a credential daemon that delivers only selected secrets. ### Offline decryption @@ -104,12 +116,12 @@ fetch them remotely. ```mermaid flowchart TB subgraph trusted["Trusted zone"] - keys["Private key material\n(systemd cred / file / keychain)"] - pm["postmaster\n(decrypt + inject)"] - child["Child process\n(your binary)"] + keys["Private key material
(systemd cred / file / keychain)"] + pm["postmaster
(decrypt + inject)"] + child["Child process
(your binary)"] end subgraph untrusted["Public zone"] - ciphertext["Encrypted .env\n(git / Nix store / artifact)"] + ciphertext["Encrypted .env
(git / Nix store / artifact)"] end subgraph outside["Outside trust boundary"] root["Root on host"] @@ -135,18 +147,20 @@ Only someone with the private key can decrypt the values. A teammate who has repository access (and thus the public key) can add or replace encrypted secrets, but cannot read existing ones. -### Plaintext never on persistent disk +### Plaintext storage depends on the deployment -Decrypted values exist only in: +The deployment must keep decrypted values in: - **Process memory** (anonymous heap, zeroized after use) - **RAM-backed filesystems** (Linux tmpfs, macOS ramdisk — destroyed when the service unit stops) -They are never written to a file on persistent disk. The tmpfs is -namespace-private (invisible outside the unit's mount namespace on -Linux) and unswappable (via `mlockall` on Linux and the service -manager's cgroup-level `MemorySwapMax=0` setting). +Postmaster writes to the configured `secrets_dir`. Without `verify_ramdisk`, +it does not prove that this directory is RAM-backed. Linux integrations must +provide a private RAM-backed mount and configure swap protection, for example +with `MemorySwapMax=0`. On macOS, enable `verify_ramdisk` to check RAM backing +before writing. Key files are separate: a `.env.keys` file can itself reside +on persistent disk. ### Fail-closed by default @@ -155,41 +169,70 @@ key file), the entire launch aborts before the child process starts. Nothing partial is injected. This is controlled by the `strict` setting, which defaults to `true`. +With `strict: false`, undecryptable dotenv values are logged and omitted. +`--verify-keys` makes those omissions fatal. Bundle authentication failures +always abort, regardless of `strict`. + ### Symlink attacks on key files and secret paths -Postmaster rejects symlinks at every point where secret material is -read or written: +Postmaster rejects final-component symlinks and checks pinned descriptors +where secret material is read or written: - **Key files** are opened with `O_NOFOLLOW` — a symlinked `.env.keys` file is rejected at the kernel level. The file descriptor is then - `fstat`-ed to verify that permissions are `0o077` (no group or world - access) and that the owner matches the current effective user ID. + `fstat`-ed to verify that no group/world permission bits are set + (`mode & 0o077 == 0`) and that the owner matches the current + effective user ID. This fd-based approach eliminates the TOCTOU window between open - and permission check. + and permission check. On macOS, the same descriptor is checked for ACL + grants that let principals other than root or the effective user read or + modify the file. File-source setup rechecks use the same validation. + Both checks leave source ACLs intact. - **Credential source paths** are checked with `symlink_metadata` before loading, rejecting symlinks at the path level. The `O_NOFOLLOW` open in `KeyRing::load` provides defense-in-depth at the fd level. -- **Secret files** are written with `O_NOFOLLOW | O_CREAT | O_TRUNC` - — a symlink planted at the target path is rejected, not followed. -- **Secrets directory** is checked with `symlink_metadata` even on - Linux where `verify_ramdisk` is not used, rejecting a symlinked - `secrets_dir` that could redirect plaintext to persistent disk. -- **Socket permissions** are set via `fchmod` on the file descriptor, - not `set_permissions` on the path, eliminating the TOCTOU window - between `bind` and `chmod`. +- **Secret files** use fresh, exclusively created 0600 inodes and atomic + publication beneath the pinned directory. Refreshes never write new + plaintext into old inodes or read handles. Foreign, hardlinked, symlinked, + and special existing files fail before mutation. On macOS, inherited ACL + grants that could expose fresh files are rejected; new file ACLs are cleared. +- **Secrets directory** is opened with `O_DIRECTORY | O_NOFOLLOW`, + rejecting a final-component symlink. With `verify_ramdisk`, the opened + inode must also belong to the verified RAM device and service user. + This checks intermediate-symlink targets as well. The launcher retains + that handle for pruning, writes, cleanup, and monitoring. Before exporting + consumer paths, Postmaster checks every lexical and resolved ancestor for + trusted ownership and protection against replacement. Trusted symlinks and + sticky shared directories remain usable; unsafe writable ancestors and + macOS ACL grants fail closed. +- **Socket permissions** use a bind-time umask on Linux and macOS, so the + pathname has its final mode from creation. Postmaster restores the prior + mask immediately afterward, including on bind failure. Binding runs + before serving threads start. Distinct consumer ownership domains cannot + share a parent or sit beneath a parent controlled by another consumer. + Alias and dot-segment checks run before any directory or socket mutation. + +Daemon entries authorize the exact dotenv source bytes with trusted +`env_file_sha256` hashes before parsing, interpolation, or decryption. The +check runs at startup and on every fetch. A file from another entry cannot +be substituted merely because it uses the same private key. Expected hashes +belong in trusted configuration, separate from mutable artifacts. Exec mode +uses its configured application inputs as the trust boundary instead. ### External binary verification -Postmaster verifies the integrity of external binaries before -invoking them in the secret path: +Keychain access on macOS uses the Security.framework API in-process — +no external binary is invoked for it. The external binaries postmaster +does invoke in secret-adjacent paths (`/usr/bin/id`, `/sbin/mount`, +`/usr/bin/hdiutil`) are verified before use: -- **macOS:** `/usr/bin/security` is verified via `codesign -v` before - being invoked for keychain access. This ensures the binary has a - valid Apple code signature and has not been tampered with or - replaced. -- **Linux:** External binaries are verified as regular files owned - by root (uid 0) and not world-writable. +- **macOS:** `codesign -v` checks the designated system binary's code + signature. The fixed system paths are also SIP-protected. +- **Linux:** verified as regular files owned by root (uid 0) with no group + or other write permissions. `id` lookup resolves system aliases, including + the NixOS system profile, verifies the target and its directory ancestry, + then invokes the resolved target. ### Input validation @@ -208,20 +251,24 @@ the secret path: `[A-Za-z_][A-Za-z0-9_]*` — this is enforced before any value from that file is used, since a key name becomes a shell-visible env-var name or a filename component. -- **No shell expansion:** Postmaster performs no `${VAR}` or `$(…)` - expansion anywhere in the decrypt-and-inject path. Values are - opaque bytes end to end. A repo contributor who commits - `KEY=$(cmd)` gets the literal string, never a command execution at - service start. +- **No shell evaluation:** decrypted values and bundle plaintext are injected + as bytes. Plaintext dotenv entries follow `dotenvy` parsing rules, including + variable substitution in unquoted and double-quoted values. Single quotes + preserve `${VAR}` literally. `$(cmd)` is not executed. Source bytes, expanded + values, assignments, and aggregate parsed output have fixed limits checked + before growth; parser errors omit input values. ### Key freshness verification Postmaster provides `--verify-keys` on `exec` to detect stale keys -from a previous rotation cycle. After loading and decrypting, if the -resolved values are empty but the env files contain `encrypted:` -values, the keys are stale and the exec aborts with a clear error. -This catches the `strict: false` case where stale keys would silently -skip undecryptable values and launch the child with no secrets. +from a previous rotation cycle. After loading and decrypting, if any +value was skipped because the key ring could not decrypt it, the exec +aborts with a clear error naming the key. This catches the +`strict: false` case where stale keys would otherwise silently skip +undecryptable values and launch the child with a partial or empty +secret set. Bundle files need no such check: bundle resolution is +all-or-nothing, so a stale bundle key already aborts the exec +regardless of `strict`. ## Residuals: what postmaster cannot fully prevent @@ -245,10 +292,36 @@ node's lifetime. ### Root on the host -A process running as root can read any other process's memory via -`/proc/PID/mem` or `ptrace`. This is the Unix trust boundary — root is -always game over. Postmaster's `PR_SET_DUMPABLE=0` and `PT_DENY_ATTACH` -prevent non-privileged peers from attaching, but cannot stop root. +A privileged process can inspect other processes through mechanisms such as +`/proc/PID/mem` or `ptrace`. Root access is outside Postmaster's trust boundary. +The launcher's `PR_SET_DUMPABLE=0` and `PT_DENY_ATTACH` checks restrict +unprivileged attachment, but don't protect against a privileged inspector. + +### Rotation timing oracle + +When multiple private keys are configured for one variable (the +comma-separated rotation convention), decryption tries each candidate in +order and stops at the first that works. A local observer measuring +launch or fetch latency can infer which candidate matched — i.e., the +rotation position of the current key. Accepted: the observer learns +only the rotation index, not key material, and already needs same-host +access; equalizing the timing would require attempting every candidate +on every decryption for no meaningful gain. + +### Env-file content is trusted input (no variable-name denylist) + +Postmaster injects what the configured env files and bundles say, +including plaintext passthrough entries. Apart from reserved private-key names, +there is no denylist of +environment variable names: names like `LD_PRELOAD` or `PATH` are +honored, because real deployments legitimately set variables of this +family (`LD_LIBRARY_PATH` is common). +The protection boundary is artifact authorship: anyone who can write the +env file (or produce valid ciphertext for it) already controls what the +child process receives. Treat plaintext passthrough entries in +world-readable artifacts as code-level intent, and keep artifact write +access tight. If a denylist is ever wanted, it belongs in config +validation as an explicit opt-in policy, not a silent default. ### Swap and core dumps @@ -257,7 +330,7 @@ persistent disk. **Core dumps** are disabled at both the process level (`PR_SET_DUMPABLE=0` on Linux, `RLIMIT_CORE=0` on macOS) and the unit -level (`LimitCORE=0`, `CoredumpFilter=0` in the Nix module). For +level when the integration sets `LimitCORE=0` and `CoredumpFilter=0`. For host-wide coverage, set `systemd.coredump.extraConfig = "Storage=none"`. @@ -266,10 +339,10 @@ host-wide coverage, set - Per-unit: the service manager (systemd) can set `MemorySwapMax=0` on the unit, preventing the kernel from swapping the unit's pages. Postmaster also calls `mlockall(MCL_CURRENT | MCL_FUTURE)` on Linux - (best-effort, may fail under `RLIMIT_MEMLOCK`). On macOS, - `mlockall(2)` does not exist, but macOS encrypts swap by default, so - swapped pages are ciphertext at rest. -- Host-wide: encrypted swap or zram keeps all swap off persistent disk. + (best-effort, may fail under `RLIMIT_MEMLOCK`). Postmaster does not lock all + memory on macOS; it relies on the platform's encrypted swap. +- Host-wide: encrypted swap protects swapped pages at rest; zram keeps + compressed swap pages in RAM. On NixOS, this is a one-liner: [`swapDevices.*.randomEncryption`](https://search.nixos.org/options?show=swapDevices.*.randomEncryption.enable) for dm-crypt with an ephemeral key, or @@ -284,17 +357,18 @@ hardening (`PR_SET_DUMPABLE=0`, `mlockall`, `RLIMIT_CORE=0`). After `execvp`, the child process gets a fresh address space. Some settings survive `execvp`, some do not: -- **`RLIMIT_CORE`**: preserved across `execve` (kernel guarantee). The - child inherits `LimitCORE=0` from the systemd unit. Core dumps stay - disabled. -- **`PR_SET_DUMPABLE`**: preserved across `execve` for non-setuid - binaries. The child inherits non-dumpable status unless it is a - setuid/setgid/capability-bearing binary (which would be unusual for - a service). +- **`RLIMIT_CORE`**: preserved across `execve`. Postmaster sets it to zero + on macOS. Linux integrations must set `LimitCORE=0` for the application; + the launcher's dumpability setting alone does not survive exec. +- **`PR_SET_DUMPABLE`**: an ordinary Linux `execve` resets dumpability to 1. + Postmaster's setting protects the launcher and credential daemon, not the + executed application. The application needs its own non-dumpable setting + or OS isolation to restrict same-UID tracing. See the + [Linux exec setup](https://github.com/torvalds/linux/blob/d48723711bae9b8cdc56719c448ba42fef28cbee/fs/exec.c#L1125-L1351). - **`MemorySwapMax=0`**: cgroup-level, not process-level. The child stays in the same cgroup, so the swap limit applies to the child's pages too. This is the primary swap protection for the child. The - Nix module sets this via `preventSwap = true` by default. + integration must configure this limit; the package does not supply a unit. - **`mlockall`**: does NOT survive `execvp` — the child's fresh address space is not pinned in RAM. This gap is covered by the cgroup-level `MemorySwapMax=0`. @@ -308,26 +382,25 @@ explicitly a non-goal. ### Anonymous memory (heap, stack) — Mitigated -Postmaster's decrypted values, key material, and resolved environment -pairs all live in anonymous memory — heap allocations wrapped in -`Zeroizing>` that zero the buffer on drop. The child process +Postmaster wraps its key ring and resolved values in `Zeroizing` buffers. +Projected environment pairs use ordinary `OsString` buffers that must remain +intact until `execvp`. The child process receives plaintext via its environment array (env mode) or reads it from files on a tmpfs/ramdisk (files/credentials mode). **Paging/swap:** Anonymous pages can be swapped out by the kernel. Postmaster mitigates this on Linux with `mlockall(MCL_CURRENT | MCL_FUTURE)` (best-effort, may fail under `RLIMIT_MEMLOCK`) and the -service manager's cgroup knob `MemorySwapMax=0` (wired by `preventSwap` -in the Nix module). On macOS, `mlockall(2)` does not exist, but macOS -encrypts swap by default, so swapped pages are ciphertext at rest. -Host-wide encrypted swap or zram on Linux provides the same guarantee -without per-unit configuration. +service manager's cgroup setting `MemorySwapMax=0`, configured by the +deployment. Postmaster does not lock all memory on macOS; it relies on +encrypted swap. Linux deployments can use encrypted swap for protection at +rest or zram to keep swap pages in RAM. **Core dumps:** Disabled at the process level (`PR_SET_DUMPABLE=0` on Linux, `RLIMIT_CORE=0` on macOS) and at the unit level -(`LimitCORE=0`, `CoredumpFilter=0` in the Nix module). Host-wide -`systemd.coredump.extraConfig = "Storage=none"` is a belt for all -units. +when configured by the integration (`LimitCORE=0`, `CoredumpFilter=0`). Host-wide +`systemd.coredump.extraConfig = "Storage=none"` disables storage for all +units handled by systemd-coredump. **Pre-execvp zeroization:** Private keys (the `KeyRing`) are zeroized when `decrypt()` returns and the `ring` local goes out of scope — @@ -337,9 +410,10 @@ explicitly `drop`ped immediately after they are consumed, before `execvp` is called. In env mode, `resolved` is dropped after `env_pairs` extracts the `OsString` pairs the kernel needs. In files mode, `resolved` is dropped after the secret files are written. -Only the `extra` vector (env array for env mode, file paths for files -mode) survives to `execvp` — and in files mode, `extra` contains only -paths, not plaintext. +The `extra` vector survives until `execvp`: it contains plaintext in env mode +and in files-mode `passthrough`, plus file pointers where applicable. The +original process environment is separate and is not zeroized. The credential +daemon retains its key ring while serving requests. ### Post-execvp heap lifetime — Residual (mitigated as far as possible) @@ -353,75 +427,114 @@ pages before reusing them, so the plaintext exists only in freed pages until the kernel reclaims them — a transient window, not a persistent risk. -No further mitigation is possible: the kernel needs the env array -to be intact at the moment of `execvp`, and `execvp` replaces the -process image without running destructors. Fork+wait would keep -secrets in a long-lived parent heap (strictly worse) and was rejected. - -### File-backed memory (page cache) — Mitigated by design - -Postmaster does not `mmap` secret files. Secret files on Linux tmpfs -and macOS ramdisk are kernel-resident RAM — they are never on -persistent disk and never enter the page cache for a backing file. -The `.env` and `.env.keys` source files are read via `dotenvy`'s -`from_read_iter` which uses `read(2)`, not `mmap(2)` — their contents -enter anonymous memory, not file-backed pages. - -The distinction matters: file-backed pages (e.g., a secret stored in a -regular file on an ext4 volume) persist in the kernel page cache after -the file is closed and the process exits. Postmaster avoids this by -writing secrets only to tmpfs/ramdisk (RAM-backed, no page cache for a -backing file) and by using `read(2)` for source files (anonymous -memory, not mapped). +The environment array must remain intact for `execvp`. Process replacement +releases the old address space without running its remaining destructors. + +### Monitor inherited heap — Mitigated + +The sibling monitor is forked after zeroization, so the key ring and +the `Zeroizing` resolved values are already wiped in the copy it +inherits. The projected `extra` array still contains plaintext in env mode +and files-mode passthrough. The monitor scrubs its copy before the +supervision loop starts: each `OsString` is consumed into its existing +buffer (no copy) and wiped in place with `zeroize` — free() alone +would leave the bytes in the monitor's mapped pages for its whole life, +and the monitor never allocates again, so they would never even be +reused. The parent's copy dies with `execvp` (image replacement). Cleanup +uses the pinned secrets-dir fd and entry names. The monitor also retains +the original process environment, which can contain private keys and other +secrets. Scrubbing `extra` does not erase that environment. + +### File-backed memory and page cache — Residual + +Postmaster reads source files into userspace buffers rather than mapping +them. That does not bypass the kernel page cache: ordinary file reads can +populate it. Zeroizing a userspace buffer does not clear the backing file +or its cached pages. See the +[Linux page-cache overview](https://docs.kernel.org/admin-guide/mm/concepts.html#page-cache). + +Keep decrypted output on RAM-backed storage. A persistent `.env.keys` file +retains its key material on disk and can leave copies in the kernel cache +after Postmaster closes it. Use credentials, RAM-backed files, or keychain +storage when persistent plaintext key files do not fit the deployment's +requirements. Swap and crash-dump protections remain separate requirements. ### Container swap enforcement — Mitigated `MemorySwapMax=0` can be wired by the service manager (systemd) or the -Nix module via `preventSwap`. This enforces the cgroup's swap limit — +deployment integration. This enforces the cgroup's swap limit — the kernel will not swap the unit's pages even under host memory -pressure. The residual is only if the host kernel itself is -compromised, which falls under "root on the host is always game over." -Host-wide encrypted swap is recommended as defense-in-depth for the -entire host, not just postmaster's cgroup. +pressure. This depends on the deployment applying the setting and on a +trusted host kernel. Host-wide encrypted swap also protects pages outside +Postmaster's cgroup. -### VM and hypervisor inspection — Residual (no mitigation available) +### VM and hypervisor inspection A hypervisor can inspect guest memory, take snapshots, or live-migrate VMs to other hosts. Postmaster's `mlockall` and `MemorySwapMax=0` operate inside the guest kernel; the hypervisor is -outside the trust boundary. The only defense is confidential computing -hardware (AMD SEV-SNP, Intel TDX, AWS Nitro Enclaves), which is -outside postmaster's scope and dependency set. +outside the trust boundary. Confidential-computing platforms can provide +additional isolation, but their setup and guarantees are outside +Postmaster's scope. -### CPU registers and cache — Non-goal (no mitigation available) +### CPU registers and cache Plaintext secrets pass through CPU registers and L1/L2/L3 cache -during decryption and injection. Postmaster does not attempt to flush -cache lines or zero registers after use. This is a non-goal: -mitigating cache-line side channels and register residue requires -constant-time crypto implementations and hardware support (e.g., TSX -memory scrubbing, `wbinvd` instruction) that are outside postmaster's -scope. The crypto library (`ecies`) uses `secp256k1` and `AES-256-GCM` -primitives that are not guaranteed constant-time on all targets; this -is a property of the crypto library, not postmaster. +during decryption and injection. Postmaster does not flush cache lines or +zero registers after use. Zeroizing its buffers does not establish that +registers, caches, or temporary copies are clear. Constant-time behavior +also depends on the crypto implementations and target hardware; Postmaster +does not guarantee it on every target. -### Privileged ptrace — Residual (no mitigation available) +### Privileged ptrace `PR_SET_DUMPABLE=0` (Linux) and `PT_DENY_ATTACH` (macOS release builds) -prevent non-privileged peers from attaching. A privileged process -(root, or a process with `CAP_SYS_PTRACE`) can still read process -memory — this is unavoidable and the same trust boundary as "root on -the host is always game over." No software mitigation exists for -privileged memory inspection within the same kernel. +restrict unprivileged attachment when those calls succeed. A process with +sufficient OS privileges can still inspect memory. Postmaster does not +provide isolation from a privileged inspector in the same kernel. ### Plaintext file persistence window (files mode) — Mitigated -Secret files written to the tmpfs/ramdisk are removed by `postmaster -cleanup --config `, wired to `ExecStopPost` in the systemd -Nix module — it runs immediately after the child exits. On macOS, the -ramdisk is destroyed when the `postmaster-ramdisk` launchd job stops. -The `prune_stale` function also removes stale files from prior -launches before writing new ones. +Secret files written to the tmpfs/ramdisk are removed by the **sibling +launch monitor**, by `postmaster cleanup --config ` wired to +`ExecStopPost` in the service integration, and by ramdisk destruction +when the `postmaster-ramdisk` launchd job stops. The `prune_stale` +function also removes stale files from prior launches before writing +new ones. + +A `TerminationGuard` blocks SIGTERM/SIGINT/SIGHUP/SIGQUIT across the +write window on both platforms when masking succeeds. Masking failures +are logged and leave that window unguarded; SIGKILL cannot be blocked. +At the end of the window, after zeroization and +before `execvp` — the launcher forks. The parent restores its pre-guard +mask and execs the service (MainPID unchanged); the fork-child is the +**sibling monitor**: it keeps the four termination signals blocked for +life and owns stop semantics. + +The monitor consumes stop signals synchronously, forwards them to the +service, and escalates to SIGKILL after a fixed 250 ms grace. The service +manager's stop timeout is separate. The monitor attempts cleanup after +forwarded stops, natural exit, `kill -9`, and crashes. Liveness uses a +pidfd with `poll` on Linux and kqueue `NOTE_EXIT` on macOS. Both report exit +without waiting for reaping; `kill(pid, 0)` polling is a fallback. + +On systemd the monitor receives its own copy of cgroup-wide stop signals. +On launchd, signals go to the job's main process, so the monitor primarily +watches for exit and cleans up. macOS forwarding uses `kill(2)` and retains +a PID-reuse risk because Darwin has no pidfd. Ramdisk teardown at job stop +provides a separate cleanup path. If the monitor dies first, cleanup depends +on `ExecStopPost`, ramdisk teardown, or the next launch's `prune_stale`. + +### Shared `secrets_dir` (multi-tenant misuse) — Documented contract + +`secrets_dir` is single-tenant per service: `prune_stale` and the +monitor's cleanup delete files based on one service's key set, so two +services sharing one directory lets one service's lifecycle delete the +other's live files. The impact is availability, not confidentiality — +no plaintext crosses services through Postmaster's resolution. Bindings must +give each service its own directory or private mount. Postmaster does not +enforce a service identity in the sentinel; directory separation is an +integration requirement. ### Ramdisk mount verification (macOS) — Mitigated @@ -431,15 +544,20 @@ Fails closed if the device isn't found or isn't RAM-backed, preventing plaintext from being written to a file-backed HFS image masquerading as the ramdisk. +The opened secrets directory's device ID must match that RAM device, +not just a lexical path prefix. Verification, pruning, writes, and cleanup +use the same pinned directory handle, so replacing a path after verification +cannot redirect those operations onto persistent storage. + ### fd closure before execvp — Mitigated -`OFlags::CLOEXEC` is set on all `rustix::fs::open` calls (5 sites) — -the kernel automatically closes these on execvp, preventing the child -from inheriting postmaster's open file descriptors. Third-party code -(e.g., dotenvy) may open fds without `CLOEXEC`; a `pre_exec` hook to -close those was considered but not implemented because it requires -unsafe code or a new cross-platform dependency. Postmaster's own fds -are fully covered. +`OFlags::CLOEXEC` is set on every file descriptor postmaster opens (all +`rustix::fs::open`/`openat` sites) — the kernel automatically closes +these on execvp, preventing the child from inheriting postmaster's open +file descriptors. Parsers receive bytes or descriptors Postmaster opens; they do +not open +paths themselves. Dotenv artifact reads also use nonblocking opens and reject +special files before reading. Postmaster's own fds are fully covered. ### Secrets directory path exposure — Mitigated diff --git a/docs/src/changelog.md b/docs/src/changelog.md deleted file mode 100644 index 71fe45a..0000000 --- a/docs/src/changelog.md +++ /dev/null @@ -1,48 +0,0 @@ -# Changelog - -All notable changes to this project are documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- Standalone postmaster binary — a format-neutral local secret - materialization engine that decrypts encrypted inputs at process - launch time, injects them into a child process, and `execvp`s the - target binary. -- `.env` input adapter — wire-compatible with dotenvx-encrypted `.env` - files (ECIES/secp256k1 + HKDF-SHA256 + AES-256-GCM). -- `postmaster_bundle` JSON container format as a second input adapter. -- `KeyNaming` enum (Env, Bundle) for compile-time exhaustive adapter - dispatch — zero vtable overhead, controlled adapter set. -- Three injection modes: `env` (environment variables), `files` - (one-file-per-secret on RAM-backed filesystem), `credentials` - (systemd credentials via postmaster daemon). -- Four key sources: systemd credentials (`LoadCredential=`), files - (`.env.keys` on disk), macOS keychain, environment variables. -- `postmaster exec --check` for config shape validation (CI). -- `postmaster setup --recheck` for runtime key source verification - (host). -- `postmaster setup` interactive command — idempotent, creates keys - directory, verifies permissions, optionally seeds keychain (macOS). -- `postmaster cleanup --config ` subcommand for plaintext - secret file removal. Wired to `ExecStopPost` in systemd. -- `--verify-keys` flag on `exec` for stale key detection after rotation. -- `OFlags::CLOEXEC` on all `rustix::fs::open` call sites. -- RAM backing verification via `hdiutil info` on macOS. -- Pre-execvp zeroization of `KeyRing` and `Resolved` values. -- Symlink rejection at every secret path: `O_NOFOLLOW`, `fstat`, - `symlink_metadata`, `fchmod` on socket fd. -- External binary verification: `codesign -v` on macOS, root-owned - check on Linux. -- Input validation: NUL byte rejection, path traversal rejection, - identifier validation, no shell expansion invariant. -- Threat model documentation covering memory residency, hardening - inheritance across execvp, and the 5-stage secret pipeline. -- `verify_key_freshness` uses `KeyNaming::Env.metadata_prefix()`. -- Two security audits conducted (provider handoff + destination - handoff), all findings fixed. -- Memory hardening audit conducted, all findings fixed. diff --git a/docs/src/executive-overview.md b/docs/src/executive-overview.md new file mode 100644 index 0000000..f484a43 --- /dev/null +++ b/docs/src/executive-overview.md @@ -0,0 +1,76 @@ +# Executive overview + +A briefing for engineering leadership and product managers on what +postmaster does, where it fits, and which protections depend on the deployment. + +## What it is + +Postmaster is a Unix tool that decrypts a service's secrets at launch and +delivers them through environment variables, files, or systemd credentials. +Its launcher replaces itself with the service binary. A separate monitor +forwards stop signals and removes secret files when the service exits. + +## The problem it solves + +Secret delivery can leave plaintext accessible beyond the process that needs it: + +- Files on persistent disk can reach backups or remain after a service stops. +- Environment variables can appear in process listings, diagnostics, or dumps. +- A wrapper that stays alive can retain its copy of keys and decrypted values. + +Postmaster decrypts at launch and wipes its key ring and resolved buffers +before replacing the launcher. The application still needs access to its +secrets for as long as it uses them. + +## Protections and their limits + +- **RAM-backed secret files.** Deployments must provide private RAM-backed + storage for file projections. The monitor removes + files after service exit, a crash, or `kill -9`, provided the monitor survives. +- **Public ciphertext.** Encrypted artifacts can live in git or a public + artifact store. Private keys need separate protection, and write access to + artifacts still controls which values the application receives. +- **Local decryption.** One Rust binary handles decryption and injection. + It has no remote secret-store client, plugin system, or shell evaluation of + secret values. The unsafe-code reference records the syscall boundaries. +- **Strict decryption by default.** A decryption failure stops launch. + `strict: false` allows undecryptable dotenv values to be omitted; + `--verify-keys` makes those omissions fatal. Bundle decryption always fails + if an entry cannot authenticate. + +## What it does not do + +- Vault, SSM, and 1Password keep custody of keys. External tooling delivers + keys to local sources before Postmaster starts. +- The service manager owns restarts and health checks. Postmaster's monitor + handles stop-signal forwarding and cleanup. +- The monitor retains the launcher's original environment. Use a file, + keychain, or credential key source to avoid leaving environment-supplied + private keys in that process. +- The optional credential daemon is long-lived and retains its key ring to + decrypt requests. It is separate from the per-service launcher and monitor. + +## Operational footprint + +- One Rust binary per host; one monitor process per service + for the service's lifetime. +- Linux with systemd and macOS with launchd. Bindings configure filesystem + permissions, credential access, RAM-backed storage, and service hardening. +- Rollout is per-service and reversible: postmaster wraps the existing + launch command. + +## Assurance posture + +- RustCrypto and released ECIES dependencies provide the cryptographic + operations. Postmaster owns the bundle's name-bound AAD envelope decoder. +- The conformance suite checks configuration examples and launch behavior. +- The threat model records residual exposure, deployment requirements, and + the limits of cleanup and memory hardening. + +## Where to go next + +| Audience | Read | +| -------- | ---- | +| Engineering leadership | This page, then the [Threat model](./architecture/threat-model.md) | +| Product / project management | This page and the [Introduction](./introduction.md) | +| Engineers integrating a service | [Quick start](./getting-started/quick-start.md) | diff --git a/docs/src/getting-started/injection-modes.md b/docs/src/getting-started/injection-modes.md index 29cad6e..1dd3e1b 100644 --- a/docs/src/getting-started/injection-modes.md +++ b/docs/src/getting-started/injection-modes.md @@ -4,39 +4,26 @@ Postmaster supports three ways to deliver decrypted secrets to the child process. Each mode makes a different tradeoff between convenience and security. -## Audience Quickstart +## Audience quickstart -**What this is:** choosing how secrets reach your application — as -environment variables, as files, or as systemd credentials. +Choose how secrets reach your application. Storage and process isolation +depend on the deployment as well as the selected mode. -| Mode | Best for | Secrets in environ? | Hygiene | +| Mode | Use | Secrets in environ? | Storage and access | | --- | --- | --- | --- | -| `env` (default) | 12-factor apps, simple services | Yes | Lowest — same-UID processes can read `/proc/PID/environ` | -| `files` | Apps that read `KEY_FILE` pointers (Docker secrets convention) | No — only `_FILE` pointers | Medium — secrets absent from environ, `ps`, crash dumps | -| `credentials` | systemd services wanting strongest isolation | No — reads `$CREDENTIALS_DIRECTORY` | Highest — unit-private unswappable ramfs | +| `env` | Apps that read environment variables | Yes | Environment copies can reach process listings, diagnostics, and child processes | +| `files` | Apps that read `KEY_FILE` pointers (Docker secrets convention) | Only when `passthrough` requests it | No environment copy by default; the app still reads plaintext files | +| `credentials` | Apps that read credential files | No additional value copy | Systemd supplies the credentials directory, or Postmaster fetches values from local sockets | -## Mode comparison +## `mode = "env"` ```mermaid -flowchart TB - subgraph env["mode: env"] - pm_env["postmaster"] -->|KEY=value\nin environ| child_env["your binary"] - end - subgraph files["mode: files"] - pm_files["postmaster"] -->|write 0600 file| tmpfs["tmpfs / ramdisk"] - tmpfs -->|KEY_FILE=/run/.../KEY| child_files["your binary"] - end - subgraph cred["mode: credentials"] - systemd["systemd"] -->|LoadCredential=| ramfs["ramfs\n$CREDENTIALS_DIR"] - pm_cred["postmaster"] -->|decrypt + write| ramfs - ramfs -->|KEY_FILE=$CREDENTIALS_DIR/KEY| child_cred["your binary"] - end +flowchart LR + pm_env["postmaster
(decrypt + inject)"] -->|"KEY=value
in environ"| child_env["your binary"] ``` -## `mode = "env"` (default) - -Decrypted values are exported into the process environment and the -wrapper `exec`s your binary. Correct for 12-factor apps. +Postmaster exports resolved values into the application environment and +replaces the launcher with your binary. **Exposure:** environment variables are readable via `/proc//environ` by root and the same UID, inherited by every child, @@ -46,14 +33,20 @@ and prone to appearing in crash dumps and debug output. means "this service only"), `ProtectProc` hardening (hides other processes' `/proc` entries), and ultimately switching to `files` mode. -**No shell expansion:** postmaster performs no `${VAR}`/`$(…)` expansion -anywhere in the decrypt-and-inject path, in any mode. A repo contributor -who commits `KEY=$(cmd)` gets the literal string, never a command -execution at service start. +**No shell execution:** decrypted values are injected without shell +evaluation. Plaintext dotenv entries follow `dotenvy` parsing rules, including +variable substitution in unquoted and double-quoted values. Single quotes +preserve `${VAR}` literally. `$(cmd)` does not execute a command. ## `mode = "files"` -Values are written one-file-per-key onto a namespace-private tmpfs +```mermaid +flowchart LR + pm_files["postmaster
(decrypt + inject)"] -->|"write 0600 file"| tmpfs["tmpfs / ramdisk
(secrets_dir)"] + tmpfs -->|"KEY_FILE=/run/postmaster/KEY"| child_files["your binary"] +``` + +Deployments provide a namespace-private tmpfs for one-file-per-key output (`TemporaryFileSystem=/run/postmaster`; on macOS, a per-service directory on an HFS RAM disk) and only `_FILE` pointer variables are exported — the Docker-secrets convention @@ -66,16 +59,24 @@ mount namespace on Linux (root needs `nsenter`) and is destroyed with the unit. On macOS, the RAM disk is protected by ownership (`0700`), not invisibility — macOS has no mount namespaces. -Each secret file is written with `O_NOFOLLOW | O_CREAT | O_TRUNC` and -`fchmod`'d to `0600` on the file descriptor (no TOCTOU window between -open and chmod). +This describes file-only projection. `passthrough` adds environment copies, +and ordinary inherited variables remain present. The application can also +copy file contents into its own memory. A hand-written config must provide +RAM-backed storage; setting `secrets_dir` alone does not verify it. -For a mostly-file-capable app with a straggler that needs an env var: +Each secret refresh publishes a fresh 0600 inode beneath the pinned directory. +Old read handles keep the old contents. Foreign, linked, and special entries +fail closed, and exported paths require protected ancestry. Trusted symlink +aliases and sticky shared parents remain supported. + +If the application reads most values from files but needs one in its +environment, list that key in `passthrough`: ```json { "mode": "files", "env_files": ["secrets/.env.production"], + "keys": [{"file": "/var/lib/postmaster/.env.keys"}], "secrets_dir": "/run/postmaster", "passthrough": ["RUST_LOG"] } @@ -86,25 +87,36 @@ rejection, since they become environment variables). ## `mode = "credentials"` -Real systemd credentials, served on demand by the postmaster daemon. -The consumer's unit gets +```mermaid +flowchart LR + daemon["postmaster credential daemon
(local socket)"] -->|"decrypted bytes
over socket"| systemd["systemd
(LoadCredential=)"] + systemd -->|"credential files"| ramfs["ramfs
$CREDENTIALS_DIRECTORY"] + ramfs -->|"KEY_FILE=$CREDENTIALS_DIRECTORY/KEY"| child_cred["your binary"] +``` + +The launcher exports `_FILE` pointers into credentials that systemd has +already supplied. Systemd can obtain those credentials from Postmaster's +daemon. In that deployment, the consumer's unit gets `LoadCredential=:/run/postmaster-credd//.sock` per key and the app reads `$CREDENTIALS_DIRECTORY/` from unit-private, **unswappable** ramfs. -No Node, no jq, no shell anywhere in the consumer's start path. The -optional wrapper only exports non-secret `_FILE` pointers. -Strongest hygiene of the three. +The launcher exports file pointers without reading the credential values. +Systemd owns their storage and access controls. -On macOS, postmaster runs `--bind` (owns its sockets), the wrapper -`postmaster fetch`es each key onto the RAM disk, and exports -`$CREDENTIALS_DIRECTORY` set to `secrets_dir` — same path convention as -systemd credentials, so app code is unchanged. +For local socket delivery, normally used with launchd on macOS, the daemon +runs with `--bind`. The launcher fetches each configured key, writes it beneath +`secrets_dir`, and exports `CREDENTIALS_DIRECTORY` along with `_FILE` +pointers. The file naming convention matches systemd credentials. The fetch +branch is selected by `sockets`, not by the operating system. ## Fail-closed rules - **`strict` (default `true`):** if any value fails to decrypt, the entire exec aborts before the child runs. Nothing partial is injected. +- **`strict: false`:** undecryptable dotenv values are logged and omitted. + `--verify-keys` makes those omissions fatal. Bundle entries must authenticate + under either setting. - **NUL in env values:** rejected in `env` mode and for `passthrough` values in `files` mode. In `files` mode's primary write path, NUL is not restricted — the exact bytes reach the file. diff --git a/docs/src/getting-started/key-provisioning.md b/docs/src/getting-started/key-provisioning.md index 8e06cbb..16b8006 100644 --- a/docs/src/getting-started/key-provisioning.md +++ b/docs/src/getting-started/key-provisioning.md @@ -3,14 +3,13 @@ This page covers how to get private keys onto hosts and how to rotate them without downtime. -## Audience Quickstart +## Audience quickstart -**What this is:** the operational side of postmaster — how the -decryption key gets to the host, and how to rotate it safely. +Provision a local private-key source and rotate it alongside encrypted inputs. | Reader | What to take | | -------- | ------------ | -| Operator / SRE | All sections — this is your playbook | +| Operator / SRE | Provisioning strategies and rotation | | Security engineer | The rotation window and fail-closed behavior | | New user | Skim strategies A and B, come back when you deploy | @@ -22,10 +21,10 @@ fetches from remote systems. ```mermaid flowchart TB subgraph sources["Key sources (local only)"] - cred["systemd credentials\n(LoadCredential=)"] - file["file\n(.env.keys on disk)"] - kc["keychain\n(macOS only)"] - env["environment\n(DOTENV_PRIVATE_KEY*)"] + cred["systemd credentials
(LoadCredential=)"] + file["file
(.env.keys on disk)"] + kc["keychain
(macOS only)"] + env["environment
(DOTENV_PRIVATE_KEY*)"] end pm["postmaster"] @@ -43,13 +42,19 @@ DOTENV_PRIVATE_KEY_PRODUCTION="<64-hex from your local .env.keys>" EOF ``` -systemd treats an absolute-path credential as mandatory: missing file -means the unit fails to start. Fail-closed. +Ownership matters: `KeyRing::load` requires the keys file to be owned +by the effective uid of the loading process, so `chown` it to the +service user (or run the file-owning step as that user) — a root-owned +keys file fails closed for a service running as a normal user. + +On macOS, runtime loading and file-source `setup --recheck` also reject ACL +grants that let anyone other than root or the effective user read or modify the +key file. These checks leave the file and its ACL intact, including read-only +files. ## Strategy B: TPM2 / host-sealed blob -Fully declarative — the key is sealed to the host's TPM2 and can only -be decrypted on that specific machine: +Seal the key to the host's TPM2 so decryption requires that host: ```console # on the target host, once (--name MUST match postmaster-) @@ -60,16 +65,21 @@ EOF # copy myapp-myhost.cred back into the repo ``` -Reference the sealed blob in your config: +Wire the sealed blob to the launcher's unit with +`LoadCredentialEncrypted=postmaster-myapp:` and reference +the credential name in your config: ```json { "keys": [ - {"file": "/nix/store/...-myapp.cred"} + {"credential": "postmaster-myapp"} ] } ``` +systemd treats the credential as mandatory: a missing or undecryptable +blob means the unit fails to start. Fail-closed. + Blobs are per-host. Without a TPM, `--with-key=host` binds to `/var/lib/systemd/credential.secret`. @@ -85,28 +95,50 @@ deployment.keys."myapp.env.keys" = { }; ``` +As with any keys file, `user` must be the service's own user — +`KeyRing::load` requires the file owner to match the loading process's +effective uid, so `root` here only works for services that run as root. + ## Strategy D: macOS Keychain +Use `postmaster setup` to seed each required Keychain account once, +in first-seen input order. By hand, use `security +add-generic-password` *without* `-w` so it prompts for the value: + ```console $ security add-generic-password -a DOTENV_PRIVATE_KEY_PRODUCTION \ - -s postmaster -w "<64-hex>" + -s postmaster ``` -No file on disk — keys live as generic-password items in the System -keychain. Postmaster reads them natively via `security(1)`. +Avoid `-w ""`: it puts the private key in the process argv, +visible to every process on the host via `ps`. + +This source stores keys as generic-password items in the default Keychain +search list. Postmaster reads them through the +Security.framework API (`security-framework` crate). + +`postmaster setup` hides terminal input for both key files and Keychain values. +It restores terminal settings when input finishes, fails, or receives a +catchable termination or suspend signal. Failed or interrupted terminal reads +discard unread input before restoration, so a partial secret cannot reach the +next terminal reader. Successful reads retain queued values. Redirected +key-file input still accepts multiple lines through EOF. `--force` publishes +a fresh 0600 key-file inode after confirmation and refuses a substituted, +foreign, linked, or special file. Existing open handles keep the old contents. ## Rotation No `rotate` subcommand exists. The flow is manual, but `DOTENV_PRIVATE_KEY*` accepts **comma-separated keys** for a -zero-downtime window: +zero-downtime window (the bundle adapter's `POSTMASTER_KEY` variable — +no per-environment suffix — follows the same convention): ```mermaid flowchart TD - step1["Step 1: Author new keypair locally\nDecrypt env, delete old pub key, re-encrypt with fresh keypair"] - step2["Step 2: Set DOTENV_PRIVATE_KEY=new,old\nBoth keys accepted; restarts decrypt either generation"] - step3["Step 3: Deploy new ciphertext\nnixos-rebuild switch — new units decrypt with new key\nOld units still running on old key"] - step4["Step 4: Drop old key (after rollback horizon)\nSet DOTENV_PRIVATE_KEY=new only\nOld generations + new-only key = broken restarts"] + step1["Step 1: Author new keypair locally
Decrypt env, delete old pub key, re-encrypt with fresh keypair"] + step2["Step 2: Set DOTENV_PRIVATE_KEY=new,old
Both keys accepted; restarts decrypt either generation"] + step3["Step 3: Deploy new ciphertext
nixos-rebuild switch — new units decrypt with new key
Old units still running on old key"] + step4["Step 4: Drop old key (after rollback horizon)
Set DOTENV_PRIVATE_KEY=new only
Old generations + new-only key = broken restarts"] step1 --> step2 step2 --> step3 @@ -126,5 +158,12 @@ Use `--verify-keys` to catch stale keys before they cause a silent failure: ```console -$ postmaster exec --config exec.json --verify-keys -- /bin/true +$ postmaster exec --config exec.json --verify-keys -- /usr/bin/true ``` + +For daemon mode, authorize the new dotenv file's SHA-256 in each entry's +`env_file_sha256` list before deploying it. Keep both old and new hashes during +the rotation window, then remove the old hash. Hashes cover the complete file, +including plaintext, comments, and line endings. Compute them from the trusted +artifact; do not derive authorization from a runtime copy that can be changed. +Exec configurations continue to select application inputs through `env_files`. diff --git a/docs/src/getting-started/quick-start.md b/docs/src/getting-started/quick-start.md index 6359621..3156402 100644 --- a/docs/src/getting-started/quick-start.md +++ b/docs/src/getting-started/quick-start.md @@ -1,17 +1,15 @@ # Quick start -This page shows how to get postmaster running with an encrypted `.env` -file in under 10 minutes. +This page launches a command with values from an encrypted `.env` file. -## Audience Quickstart +## Audience quickstart -**What this is:** a hands-on walkthrough of the simplest path — -encrypting secrets, provisioning keys, and launching a service with -postmaster. +Encrypt a dotenv file, provision its private key, and launch a command with +Postmaster. ## Prerequisites -- A Rust toolchain (`rustup`, stable) +- Rust 1.99.1 or newer (`rustup`, stable) - [dotenvx CLI](https://github.com/dotenvx/dotenvx) (or any tool producing the same ECIES format) for encrypting secrets - postmaster built from source (or from the Nix flake) @@ -21,6 +19,7 @@ postmaster. Create a `.env` file and encrypt it: ```console +$ mkdir -p secrets $ dotenvx set DATABASE_URL 'postgres://user:pass@localhost:5432/myapp' \ -f secrets/.env.production $ dotenvx set API_TOKEN 'secret-token-here' \ @@ -39,14 +38,21 @@ API_TOKEN="encrypted:BGAAAAAADWyy..." ## Step 2: Provision keys -Postmaster needs the private key to decrypt the values. The key lives in -a `.env.keys` file: +Postmaster needs the private key to decrypt the values. `dotenvx set` +above wrote it to a `.env.keys` file alongside your env file: ```console -$ dotenvx keys -f secrets/.env.production -DOTENV_PRIVATE_KEY_PRODUCTION="a1b2c3d4e5f6..." +$ cat secrets/.env.keys +DOTENV_PRIVATE_KEY_PRODUCTION=a1b2c3d4e5f6... ``` +> **dotenvx version note:** the CLI changes across releases. Older +> versions exposed the private key through a `dotenvx keys` subcommand +> (since removed); current versions write it to the `.env.keys` file +> next to your env file, and the value may be quoted or unquoted +> depending on version. Treat the `.env.keys` file as the durable +> source — copy the `DOTENV_PRIVATE_KEY_*` value from it. + Place the keys file on the host (Linux): ```console @@ -56,17 +62,28 @@ DOTENV_PRIVATE_KEY_PRODUCTION="a1b2c3d4e5f6..." EOF ``` -On macOS, you can also use the keychain: +Ownership matters: `KeyRing::load` requires the keys file to be owned +by the effective uid of the loading process, so `chown` it to the +service user (or run the file-owning step as that user) — a root-owned +keys file fails closed for a service running as a normal user. + +On macOS, you can also use the keychain. The recommended path is +`postmaster setup`, which seeds keychain items interactively; the +equivalent by hand is `security add-generic-password` *without* `-w`, +which prompts for the value: ```console $ security add-generic-password -a DOTENV_PRIVATE_KEY_PRODUCTION \ - -s postmaster -w "a1b2c3d4e5f6..." + -s postmaster ``` +Avoid `-w ""`: it puts the private key in the process argv, +visible to every process on the host via `ps`. + ## Step 3: Create exec.json -Postmaster reads an `exec.json` config that specifies what to decrypt, -how to inject, and what binary to launch: +The `exec.json` config selects inputs, key sources, and projection mode. +You supply the command to launch separately after `--`: ```json { @@ -104,10 +121,9 @@ DATABASE_URL=postgres://user:pass@localhost:5432/myapp API_TOKEN=secret-token-here ``` -Postmaster decrypted the values, injected them as environment variables, -and `execvp`'d `/usr/bin/env` — which printed them. In a real deployment, -the service manager (systemd or launchd) runs postmaster, which -replaces itself with your binary. +Postmaster decrypts the values, exports them as environment variables, and +replaces the launcher with `/usr/bin/env`, which prints them. In a deployment, +systemd or launchd runs Postmaster with your service command instead. ```mermaid flowchart TB diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 6d3be87..7afaae3 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,28 +1,25 @@ # Introduction -postmaster is a **standalone, format-neutral local secret materialization -engine**. It decrypts encrypted secret inputs at process launch time and -injects them into a child process via environment variables, files, or -systemd credentials — then `execvp`s the target binary directly. No Node, -no shell, no separate CLI process in the runtime path. +Postmaster decrypts local secret inputs at process launch and delivers values +through environment variables, files, or systemd credentials. It then replaces +the launcher with the target binary through `execvp`. -## Audience Quickstart (Plain Language) +## Audience quickstart -**What this is:** a tool that takes encrypted secrets (like database -passwords and API tokens) and safely puts them into your service's -environment at startup — without writing plaintext to disk, without -running a shell, and without keeping a long-lived parent process that -holds secrets in memory. +Decryption runs in Rust. Postmaster doesn't evaluate secret values as shell +code. Deployments provide RAM-backed storage for file projections and +configure swap and dump protection. The service manager owns the service; +a sibling monitor handles stop-signal forwarding and file cleanup. ### Who this is for -| Reader | What to take from this docs | +| Reader | What to take from this doc | | -------- | ------------------------------ | | New user / junior engineer | The introduction and [Quick start](./getting-started/quick-start.md); then [Injection modes](./getting-started/injection-modes.md) | | Platform / SRE | [Key provisioning](./getting-started/key-provisioning.md) and the [Threat model](./architecture/threat-model.md) | | Security engineer | The [Threat model](./architecture/threat-model.md) and [Materialization ABI](./architecture/materialization-abi.md) | | Integration author | The [Launcher contract](./reference/launcher-contract.md) and [CLI reference](./reference/cli.md) | -| Product / project manager | This introduction and the [postmaster](./architecture/postmaster.md) overview | +| Product / project manager, engineering leadership | The [Executive overview](./executive-overview.md), then this introduction | ### Quick glossary @@ -31,124 +28,101 @@ holds secrets in memory. | **Materialization** | Decrypting secrets and putting them where your app can read them (env vars, files, or credentials) | | **execvp** | A Unix system call that replaces the current process with a new binary — postmaster becomes your app | | **ECIES** | Elliptic Curve Integrated Encryption Scheme — the crypto used to encrypt individual secret values | -| **exec.json** | A JSON config file that tells postmaster what to decrypt, how to inject, and what binary to launch | +| **exec.json** | A JSON config file that selects inputs, key sources, and projection mode. The command to launch is supplied separately after `--`. | | **Key source** | Where the decryption key comes from (a file, systemd credentials, macOS keychain, or environment) | | **Injection mode** | How decrypted secrets reach the child: `env` (environment variables), `files` (one file per secret), or `credentials` (systemd credentials) | | **Ciphertext** | Encrypted data — safe to store in git, the Nix store, or any world-readable location | -## The Core Problem +## The core problem -Deploying secrets to production services is hard. The secrets need to -be present at runtime, but they must not be stored in plaintext on disk, -in the container image, or in the deployment manifest. Common approaches -each have tradeoffs: +Services need secrets at runtime. Storing them in plaintext in a container +image, deployment manifest, or persistent file creates additional copies to +protect. Delivery methods have different exposure: -- **Shell wrappers** run a script that `eval`s secrets — vulnerable to - command injection if a secret contains `$(...)` or backticks. -- **External CLIs** (Node, Python) stay alive as a parent process — - secrets persist in the parent's heap for the service's entire lifetime. -- **Sidecar containers** inject secrets over the network — adds a - network dependency to the startup path. -- **Manual env vars** put plaintext secrets in the systemd unit file or - the container spec — visible in `ps`, `systemctl cat`, and crash dumps. +- **Shell wrappers** that evaluate secret values as code can execute + `$(...)` or backticks embedded in those values. +- **Parent processes** that stay alive can retain keys and decrypted values + for the service's lifetime. +- **Network delivery** adds a dependency to the startup path. +- **Plaintext environment configuration** can expose values through unit + files, container specifications, process listings, and dumps. -Postmaster takes a different approach: decrypt locally, inject directly, -replace the process image. The secret material exists in process memory -for a brief window, never touches persistent disk, and the process that -held the secrets is gone the moment your binary starts. +Postmaster decrypts locally, injects directly, and replaces the launcher +with your binary. It wipes its key ring and resolved buffers before launch. +Deployments provide RAM-backed secret storage and configure swap and dump +protection. The application keeps access to the secrets it uses. -## What postmaster Does +## What Postmaster does 1. **Decrypts** encrypted `.env` files (or `postmaster_bundle` JSON - containers) using the `ecies` crate — native Rust, no network calls, - no external CLIs, no shell. + containers) using native Rust cryptography. Bundle entries use Postmaster's + AAD decoder with released ECIES helpers and RustCrypto AES-GCM. 2. **Injects** decrypted values into the child via one of three modes: - `env` — environment variables (12-factor apps) - `files` — one file per secret on a RAM-backed filesystem (Docker secrets convention, `KEY_FILE` pointers) - - `credentials` — systemd credentials (strongest hygiene) + - `credentials` — pointers to systemd credentials or values fetched + from configured local sockets 3. **Launches** the target binary via `execvp` — postmaster is replaced - by your binary. The child process IS `MainPID` from its first - instruction. No parent process holds secrets. + by your binary. The service process remains `MainPID` from its first + instruction. A sibling monitor handles stop signals and file cleanup. 4. **Cleans up** — `postmaster cleanup` removes plaintext secret files after the child exits, wired to `ExecStopPost` in systemd. -## How postmaster Works +## How Postmaster works ```mermaid flowchart LR - store["Encrypted .env file\n(nix store / git / artifact)"] - keys["Private key\n(systemd cred / file / keychain)"] + store["Encrypted .env file
(nix store / git / artifact)"] + keys["Private key
(systemd cred / file / keychain)"] pm["postmaster exec"] - child["Your binary\n(MainPID)"] + child["Your binary
(MainPID)"] store --> pm keys --> pm pm -->|decrypt + inject| child - pm -.->|execvp replaces\npostmaster| child + pm -.->|execvp replaces
postmaster| child ``` The ciphertext is designed to be public. Every value is ECIES/secp256k1-encrypted individually — the public key embedded in the file only permits encrypting new values, never decrypting existing -ones. So the world-readable Nix store, git repo, or artifact registry -stops being an adversary. The entire secret surface collapses to one -64-hex private key per environment. +ones. This allows encrypted values in the Nix store, git, or an artifact +registry. Private keys still need separate protection. Anyone with the public +key can encrypt replacement values, so artifact write access remains trusted. -## The Secret Pipeline +## The secret pipeline -Postmaster owns exactly one stage in a 5-stage pipeline. Understanding -which stage each system owns is the key to understanding what postmaster -is (and is not). +Postmaster handles local materialization and process launch in this pipeline: +custody +(Vault/SSM/1Password/TPM2) → rendering (Nix/Terraform/CDK/Ansible) → +delivery (systemd credentials/files/keychain/env) → **materialization +(postmaster)** → launch (execvp). The stage diagram, table, and +per-stage detail live in +[postmaster — the secret pipeline](./architecture/postmaster.md#the-secret-pipeline). -```mermaid -flowchart LR - subgraph s1["1. Custody"] - vault["Vault / SSM /\n1Password / TPM2"] - end - subgraph s2["2. Rendering"] - nix["Nix / Terraform /\nCDK / Ansible"] - end - subgraph s3["3. Delivery"] - cred["systemd cred /\nfile / keychain"] - end - subgraph s4["4. Materialization"] - pm["postmaster\ndecrypt + inject"] - end - subgraph s5["5. Launch"] - exec["execvp\nchild = MainPID"] - end - - vault --> nix - nix --> cred - cred --> pm - pm --> exec -``` - -| Stage | Who owns it | What happens | -| ----- | ----------- | ------------ | -| 1. Custody | Vault, AWS SSM, 1Password, TPM2 | Private keys live in a source/custody system | -| 2. Rendering | Nix, Terraform, CDK, Ansible, Salt, Puppet | Encrypted artifacts + key material + service wiring get onto the host | -| 3. Delivery | systemd, files, keychain, env | Key material reaches postmaster at runtime via local sources | -| 4. Materialization | **postmaster** | Postmaster decrypts and injects — this is the only stage it owns | -| 5. Launch | execvp | Process image replaced; child binary is MainPID | +External tools own custody, rendering, and delivery. Postmaster doesn't fetch +from remote stores or deploy infrastructure. Its monitor forwards stop signals +and cleans up plaintext files; the service manager owns restarts and health +checks. -Postmaster does not participate in stages 1-3. It does not fetch from -remote systems, does not deploy infrastructure, and does not supervise -the child process. It decrypts, injects, and gets out of the way. +The monitor scrubs the projected environment pairs, but retains the original +process environment. Environment-supplied private keys can remain there. +The optional credential daemon also retains its key ring while serving +requests. See the [Threat model](./architecture/threat-model.md) for these +limits and the deployment requirements. -## Capability Horizon +## Capabilities and scope - `.env` adapter (wire-compatible with dotenvx), `postmaster_bundle` JSON container, three injection modes, four key sources (systemd credentials, files, keychain, environment), `--verify-keys` freshness check, `setup` command, `cleanup` command. -- **Non-goals:** postmaster will never become a network client for Vault, - SSM, or any remote secret store. It will not add a plugin system, an - async runtime, or a CLI parsing library. +- **Scope:** remote secret-store clients, plugin systems, an async runtime, + and a CLI parsing library are outside Postmaster's runtime contract. ## First input adapter @@ -158,8 +132,6 @@ The first input adapter is wire-compatible with existing `.env` files encrypted with the dotenvx CLI decrypt byte-exact through postmaster's native Rust implementation. -dotenvx is one adapter, not the ceiling — the architecture supports -file-based (`.env`), HashiCorp Vault, AWS SSM, and other secret providers -as source/custody backends. But those systems deliver key material to -local terminal sources; postmaster reads from those local sources and -never reaches across the network. +The bundle adapter provides a second input format. Vault, AWS SSM, and other +custody systems can deliver key material to local sources before launch. +Postmaster reads those local sources; it doesn't contact the remote store. diff --git a/docs/src/reference/cli.md b/docs/src/reference/cli.md index 11d7596..ebbca46 100644 --- a/docs/src/reference/cli.md +++ b/docs/src/reference/cli.md @@ -1,8 +1,6 @@ # CLI reference -All postmaster commands, flags, and exit codes. The CLI is hand-rolled -with no external parsing library — every flag below is the complete -set, directly from the argument parser in `config.rs`. +Commands, flags, and exit codes accepted by `src/cli/mod.rs`. ## Synopsis @@ -26,9 +24,10 @@ $ postmaster --help ## Default mode (serve) -When no subcommand is given, postmaster enters daemon (serve) mode. This -is the credential server used in credentials injection mode — -socket-activated on Linux, self-binding on macOS. +Serve mode has no subcommand keyword — invoke it with the serve flags +directly. This is the credential server used in credentials injection +mode — socket-activated on Linux, self-binding on macOS. (Bare +`postmaster` with no arguments prints the top-level help and exits 1.) ```console $ postmaster --config [--bind] [--allow-nonroot] @@ -38,13 +37,36 @@ $ postmaster --config [--bind] [--allow-nonroot] | --- | --- | | `--config ` | Configuration file (required) | | `--bind` | Bind listener sockets even if not socket-activated (macOS) | -| `--allow-nonroot` | Allow non-root connections (dangerous) | +| `--allow-nonroot` | Allow non-root connections (dev escape hatch; never overrides a configured `peer_user` ACL) | On Linux, postmaster is socket-activated: the `postmaster-credd.socket` unit owns the sockets and the daemon inherits them via `sd_listen_fds`. On macOS, `--bind` causes postmaster to create its own listener sockets. +### Daemon configuration + +Each socket maps to an entry with `env_file`, `key`, `env_file_sha256`, and +optional `peer_user`. `env_file_sha256` is a list of SHA-256 hashes, encoded +as 64 hex digits, for the exact dotenv file bytes authorized for that entry. +Postmaster checks the hash before parsing, interpolation, or decryption, both +at startup and on every fetch. An empty list authorizes nothing. This applies +to plaintext assignments too. + +Keep this configuration under trusted ownership. Compute hashes from the +trusted artifact before deployment, rather than from the writable runtime +copy. On Linux, use `sha256sum `; on macOS, use `shasum -a 256 `. +Line endings, whitespace, and metadata count toward the hash. Multiple hashes +allow old and new files during staged rotation; remove the old hash when that +window ends. The dotenvx ciphertext format and private-key rotation candidates +stay the same. + +When binding as root, sockets for different unprivileged peers need separate +parent directories. One peer's parent cannot contain another peer's socket +parent. Postmaster resolves aliases and checks these ownership domains before +changing directories or binding sockets. Sockets for the same user can share +a parent; root-only entries and `peer_user` resolving to uid 0 share a domain. + ## exec Decrypt and inject secrets, then `execvp` the target binary. @@ -64,25 +86,26 @@ $ postmaster exec --config [--check] [--verify-keys] -- [a returns. - On failure the error is logged and the process exits non-zero. - `--check` does not accept a command after `--`. +- `--check` combined with `--verify-keys` silently ignores verification — + check validates the config shape and never decrypts. - `--verify-keys` performs a preflight check: after loading and - decrypting, if the resolved values are empty but the env files - contain `encrypted:` values, the keys are stale and the exec - aborts. This catches the `strict: false` case where stale keys - would silently skip undecryptable values. + decrypting, if any value was skipped because the key ring could not + decrypt it, the keys are stale and the exec aborts naming the key. + This catches the `strict: false` case where stale keys would + otherwise silently skip undecryptable values (partial or empty set). Exit codes: | Code | Meaning | | --- | --- | | 0 | `--check` passed (or exec succeeded — but exec replaces the process) | -| 1 | Config error, parse failure, decryption failure | -| 2 | Missing arguments, bad usage | +| 1 | Any failure — usage errors, config errors, parse failure, decryption failure | ## setup -Create keys directory, verify permissions, optionally seed keychain -(macOS), validate environment. Idempotent — skips steps that are -already correct. +Create the keys directory, check key sources, and optionally seed macOS +Keychain accounts. Setup skips steps that are already satisfied. It derives +one required-account list in first-seen input order, without duplicate prompts. ```console $ postmaster setup --config [--recheck] [--unattended] [--force] [--keys-dir ] @@ -99,7 +122,21 @@ $ postmaster setup --config [--recheck] [--unattended] [--force] [-- Default keys directory: - Linux: `/var/lib/postmaster` -- macOS: `~/Library/Application Support/postmaster` +- macOS: `~/Library/Application Support/postmaster` (falls back to + `/var/lib/postmaster` when `HOME` is unset) + +Secret terminal input has echo disabled until the read finishes. Postmaster +restores terminal settings before delivering a pending termination or suspend +signal. Key files accept multiline input through EOF; Keychain values use one +trimmed line. Failed or interrupted terminal reads discard unread input before +restoration. Successful reads retain queued values. Redirected input keeps the +same format and buffering. + +Forced key-file replacement verifies ownership, regular-file type, and single +link count before changing permissions. It pins the parent, checks that the +original inode still occupies the name after input, and publishes a fresh +0600 inode. Existing read handles keep the old contents. A declined replacement +keeps the existing contents; unattended replacement fails without prompting. ## cleanup @@ -114,14 +151,22 @@ $ postmaster cleanup --config | --- | --- | | `--config ` | Path to `exec.json` (reads `secrets_dir` from config) | -Wired to `ExecStopPost` in systemd by the Nix module. On macOS, the +Cleanup refuses to bulk-delete a non-empty directory without the +`.postmaster-managed` sentinel. The marker identifies a managed directory, +not individual files, so keep one `secrets_dir` per service. Empty or missing +directories need no cleanup. If a secret-file stat or removal fails, the command +retains the sentinel and returns an error so cleanup can be retried. Removing +the sentinel after successful cleanup is best effort. + +Integrations can wire this to `ExecStopPost` in systemd. On macOS, the ramdisk destruction handles cleanup automatically when the launchd job stops. ## fetch -macOS credential fetch client — connects to a postmaster socket and -reads the decrypted value to EOF. +Connect to a local Postmaster socket and write its decrypted value to stdout. +Reads stop at EOF and are capped at 16 MiB; an oversized stream fails without +truncating the value. This command is available on Linux and macOS. ```console $ postmaster fetch /run/postmaster-credd/myapp/DATABASE_URL.sock @@ -132,7 +177,9 @@ typically called directly. ## help -Print help text for a subcommand or the top-level help. +Print help text for a subcommand or the top-level help. Every +subcommand also accepts `--help`/`-h` directly (`postmaster exec +--help`). ```console $ postmaster help # top-level help diff --git a/docs/src/reference/launcher-contract.md b/docs/src/reference/launcher-contract.md index 0b710b8..c053b90 100644 --- a/docs/src/reference/launcher-contract.md +++ b/docs/src/reference/launcher-contract.md @@ -1,10 +1,9 @@ # Launcher contract (exec.json) -## Audience Quickstart (Plain Language) +## Audience quickstart -**What this is:** the complete specification of `exec.json` — every -field, every mode, every validation rule. This is the contract a -binding (Nix, Terraform, CDK, Ansible) must produce. +This reference defines the fields, modes, and validation rules for `exec.json`. +Deployment integrations must generate this format. ### Who this is for @@ -19,18 +18,17 @@ binding (Nix, Terraform, CDK, Ansible) must produce. | Term | Plain meaning | | ------ | --------------- | -| **exec.json** | JSON config that tells postmaster what to decrypt and how to launch | +| **exec.json** | JSON config that selects inputs, key sources, and projection mode. The launch command follows `--` separately. | | **Projection mode** | How secrets reach the child: env, files, or credentials | | **Key source** | Where the decryption key comes from (file, credential, keychain, env) | -| **Strict** | If true (default), any decryption failure aborts the launch | +| **Strict** | If true, dotenv decryption failures abort launch. Bundle authentication failures abort under either setting. | | **Passthrough** | In files mode, specific keys also exported as env vars | `postmaster exec` is the concrete instance of the [materialization ABI](../architecture/materialization-abi.md). -The current config shape is -the `.env` adapter: encrypted inputs are `env_files`, private key material uses -the `.env.keys` / `DOTENV_PRIVATE_KEY*` convention, and output projection is -selected with `mode`. This page documents the committed parser and launcher +The config accepts dotenv inputs through `env_files` and JSON bundles through +`bundle_files`. They use `DOTENV_PRIVATE_KEY*` and `POSTMASTER_KEY` respectively; +`mode` selects output projection. This page documents the parser and launcher behavior; the ABI page records how this contract fits into the broader format-neutral architecture. @@ -43,25 +41,23 @@ hand-rolled process supervisors, or nix-darwin's launchd — get the same decrypt-and-inject semantics as the Linux daemon path, without templating shell or re-implementing the crypto. -This page is **the** cross-binding contract. The Nix module is the first -binding to emit `exec.json`; it is not privileged over any other binding. -**A binding is correct if and only if the `exec.json` it emits is -described by this document and passes the conformance suite.** -Nothing here documents intent or a roadmap; every claim below is true -of the committed parser and launcher (`src/config.rs`, -`src/launcher.rs`, `src/keys.rs`) as of this writing. +This is the cross-binding contract. Nix and other deployment integrations +emit the same `exec.json` format. +Bindings must emit configs accepted by the parser and check their behavior +against the conformance suite. Host permissions, key availability, and +service-manager wiring require separate validation. ### Config to launch flow ```mermaid flowchart TD - cfg["exec.json\n(mode, keys, env_files)"] - check["--check\nconfig shape only"] - recheck["setup --recheck\nkey source accessible?"] - resolve["resolve_all\ndecrypt + resolve"] - verify["--verify-keys\nstale key check"] - inject["inject\n(env / files / credentials)"] - execvp["execvp\nchild = MainPID"] + cfg["exec.json
(mode, keys, env_files, bundle_files)"] + check["--check
config shape only"] + recheck["setup --recheck
key source accessible?"] + resolve["resolve_all + resolve_bundle
decrypt + resolve"] + verify["--verify-keys
stale key check"] + inject["inject
(env / files / credentials)"] + execvp["execvp
child = MainPID"] cfg --> check cfg --> recheck @@ -77,11 +73,9 @@ The `.env` semantics this contract mirrors — encrypted-value format, `.env.keys` rotation via comma-separated candidates, `DOTENV_PRIVATE_KEY*` naming, `--strict`/`--overload` precedence — are wire-compatible with [dotenvx](https://github.com/dotenvx/dotenvx)-encrypted `.env` files. -`postmaster exec` does not shell out to any external CLI at all — it -implements the decrypt path natively in Rust (same `ecies` crate the -daemon uses) — but wherever this document describes a precedence or -filtering rule, it describes the wire-compatible behavior, not a -postmaster-only invention. +`postmaster exec` decrypts natively in Rust, using the same dotenv ECIES +path as the daemon. It does not invoke an external encryption CLI. +Platform checks can invoke verified system tools, as described below. ## Invocation @@ -100,18 +94,21 @@ $ postmaster cleanup --config reading key material, checking the filesystem, fetching sockets, or launching the child command. It does not accept a command after `--`. - `--verify-keys` performs a preflight check: after loading and decrypting, - if the resolved values are empty but the env files contain `encrypted:` - values, the keys are stale (from a previous rotation cycle) and the exec - aborts with a clear error. This catches the `strict: false` case where - stale keys would silently skip undecryptable values and launch the child - with no secrets. + if any value was skipped because the key ring could not decrypt it + (stale keys from a previous rotation cycle), the exec aborts with a + clear error naming the key. This catches the `strict: false` case where + stale keys would otherwise silently skip undecryptable values and + launch the child with a partial or empty secret set. Bundle files need + no such check: bundle resolution is all-or-nothing, so a stale bundle + key already aborts the exec regardless of `strict`. - `setup` verifies platform prerequisites, creates keys directory with 0700, verifies/creates keys files with 0600, optionally seeds keychain items (macOS), and validates the environment. Idempotent. `--recheck` is verification-only. `--unattended` fails closed without prompting. `--force` re-creates/re-seeds even if correct. `--keys-dir` overrides the default path (`/var/lib/postmaster` on Linux, - `~/Library/Application Support/postmaster` on macOS). + `~/Library/Application Support/postmaster` on macOS — falling back to + `/var/lib/postmaster` when `HOME` is unset). **`--check` validates config shape only, not key source accessibility:** a config can pass `--check` in CI but fail at runtime because the key file is missing, the keychain item is absent, or the credential source @@ -126,7 +123,7 @@ $ postmaster cleanup --config ## `ExecConfig` fields -`exec.json` deserializes into this struct (`src/config.rs`). +`exec.json` deserializes into this struct (`src/exec_config.rs`). Unknown root fields are rejected. ABI fields such as `version` or `adapter` must not be emitted until the parser and schema explicitly define them. A machine-readable JSON Schema for this current shape is kept at @@ -138,16 +135,16 @@ Every field except `mode` has a default, so a minimal config is just | Field | Type | Default | Meaning | |---|---|---|---| | `mode` | `"env" \| "files" \| "credentials"` | — (required) | Injection mode; see below. | -| `keys` | array of key-source specs | `[]` | Ordered list of where to obtain `DOTENV_PRIVATE_KEY*` material. Unused in `credentials` mode. | -| `env_files` | array of paths | `[]` | Encrypted `.env[.]` files, in precedence order (first file wins unless `overload`). Required (non-empty) for `env`/`files` modes. | -| `bundle_files` | array of paths | `[]` | Encrypted `postmaster_bundle` JSON containers, in precedence order. Entries are merged with `env_files`; bundle keys use the same identifier rule and injection modes. | -| `strict` | bool | **`true`** | Any value that fails to decrypt aborts the whole exec before the child runs. | +| `keys` | array of key-source specs | `[]` | Ordered list of where to obtain `DOTENV_PRIVATE_KEY*` / `POSTMASTER_KEY` material. Unused in `credentials` mode. | +| `env_files` | array of paths | `[]` | Encrypted `.env[.]` files, in precedence order (first file wins unless `overload`). `env`/`files` modes require at least one of `env_files` or `bundle_files` non-empty. | +| `bundle_files` | array of paths | `[]` | Encrypted `postmaster_bundle` JSON containers, resolved after `env_files`. The first definition wins unless `overload` selects the last; bundle keys use the same identifier rule and injection modes. | +| `strict` | bool | **`true`** | Undecryptable dotenv values abort launch when true and are omitted when false. Bundle authentication failures always abort. | | `overload` | bool | `false` | File-derived values override the process environment; later files override earlier ones. | -| `secrets_dir` | path or `null` | `null` | `files` mode, and `credentials` mode on the launchd/fetch path: directory plaintext files are written into. | +| `secrets_dir` | path or `null` | `null` | `files` mode, and `credentials` mode on the socket-fetch path: directory plaintext files are written into. | | `passthrough` | array of strings | `[]` | `files` mode only: these keys are *also* exported as real env vars, in addition to their `_FILE` pointer. | | `credential_keys` | array of strings | `[]` | `credentials` mode: keys to expose as `$CREDENTIALS_DIRECTORY/`. Required (non-empty) for that mode. | -| `sockets` | map of key → socket path | `{}` | `credentials` mode: postmaster socket to fetch `` from. Non-empty selects the darwin/launchd fetch path; empty means systemd already materialized the credentials via `LoadCredential=`. | -| `verify_ramdisk` | path or `null` | `null` | darwin only: refuse to write plaintext unless this mount point is the HFS ramdisk and `secrets_dir` is a directory owned by the current euid. | +| `sockets` | map of key → socket path | `{}` | `credentials` mode: postmaster socket to fetch `` from. Non-empty selects local socket fetching on either OS; empty means systemd already materialized the credentials via `LoadCredential=`. | +| `verify_ramdisk` | path or `null` | `null` | darwin only: require a RAM-backed HFS mount and a service-owned `secrets_dir` on that device. The verified directory handle is retained for plaintext I/O. | Note the field name is `verify_ramdisk`, not `ramdisk` or `ramdisk_mount` — match it exactly. @@ -155,13 +152,22 @@ match it exactly. Mode-required fields are enforced by `postmaster exec --check` and again before a real launch: -- `env` requires non-empty `keys` and non-empty `env_files`. -- `files` requires non-empty `keys`, non-empty `env_files`, and - `secrets_dir`. +- `env` requires non-empty `keys` and at least one of `env_files` or + `bundle_files` non-empty. +- `files` requires non-empty `keys`, at least one of `env_files` or + `bundle_files` non-empty, and `secrets_dir`. - `credentials` requires non-empty `credential_keys`. If `sockets` is non-empty, it also requires `secrets_dir` and a socket mapping for every credential key. +**One `secrets_dir` per service.** postmaster treats `secrets_dir` as +single-tenant: `prune_stale` at launch and cleanup on every death path +delete files there based on one service's key set, so two services +sharing a directory lets one service's lifecycle delete the other's live +files (an availability failure — plaintext never crosses services). The +integration must separate services, for example with a namespace-private +tmpfs per Linux unit or per-service directories on a macOS RAM disk. + `--check` also validates env-file basenames, rejects private-key `file` sources under `/nix/store`, rejects path-like `credential` source names, and applies identifier validation to `passthrough` and @@ -179,7 +185,7 @@ serde fills those in even when the generator omits the field. |---|---| | `env` | `secrets_dir`, `credential_keys`, `sockets`, `verify_ramdisk`, `passthrough` | | `files` | `credential_keys`, `sockets` | -| `credentials` | `keys`, `env_files`, `overload`, `passthrough` | +| `credentials` | `keys`, `env_files`, `bundle_files`, `overload`, `passthrough` | ## Key-source list (`keys`) @@ -189,8 +195,24 @@ Each entry in `keys` is one externally-tagged JSON shape: |---|---| | `{"credential": ""}` | `$CREDENTIALS_DIRECTORY/` (the launcher's *own* `LoadCredential`, i.e. `.env.keys` handed to it the same way postmaster's daemon receives its own). `` must be a single relative path component, not `.`, `..`, an absolute path, or a slash-containing path. | | `{"file": ""}` | An out-of-store `.env.keys`-format file read directly. Rejected outright if the path starts with `/nix/store` — private keys must never live in the world-readable store. | -| `{"keychain": ""}` | macOS System keychain; one generic-password item per `DOTENV_PRIVATE_KEY[_]` account, service name as given. Only the variables actually needed (derived from `env_files`) are fetched. Any other target: error, "only available on macOS". | -| `"environment"` | The unit-variant source — note it is a bare JSON string, not an object, because it carries no data. Reads `DOTENV_PRIVATE_KEY*` straight from postmaster's own process environment. | +| `{"keychain": ""}` | macOS keychain (the default keychain search list); one generic-password item per `DOTENV_PRIVATE_KEY[_]` account, service name as given. Only the variables actually needed (derived from `env_files` and `bundle_files`) are fetched. Any other target: error, "only available on macOS". | +| `"environment"` | The unit-variant source — note it is a bare JSON string, not an object, because it carries no data. Reads `DOTENV_PRIVATE_KEY*` (and `POSTMASTER_KEY` when `bundle_files` are configured) straight from postmaster's own process environment. | + +**Bundle key variable.** With `bundle_files` configured, the ring admits +`POSTMASTER_KEY` material in the same sources: comma-separated rotation +candidates are admitted, and `POSTMASTER_KEY_` variants match by +the same predicate as `DOTENV_PRIVATE_KEY_*`. There is no +per-environment filename mapping — every bundle file resolves against +the one `POSTMASTER_KEY` variable. `profile` and `recipients` are public +metadata; they do not select keys. Bindings select the bundle paths. + +**Application environment.** In every projection mode, the launched command +does not receive `DOTENV_PRIVATE_KEY`, `POSTMASTER_KEY`, or their +`_` variants. This applies regardless of the selected key +source and after all projected values are added. Other inherited variables, +including `PATH` and `HOME`, are preserved. Bundle entries using these +reserved private-key names are rejected before launch, even with +`strict: false`. **Selection contract**, evaluated in list order: @@ -212,13 +234,13 @@ decryption happens in that mode; see below. ## Precedence contract -This is the contract `resolve_all` (`src/keys.rs`) implements, -verbatim: +The launcher resolves `env_files` first, followed by `bundle_files`. +Both adapters follow this contract: - **Within one file, the last assignment wins** — ordinary dotenv semantics. `A=1` followed later in the same file by `A=2` yields `2`. - **Across files, the first file that defines a key wins**, in the order - `env_files` lists them — *unless* `overload` is `true`, in which case + the lists specify — *unless* `overload` is `true`, in which case the **last** file defining the key wins. Note: which file wins does not change the *position* a key is emitted in; a key's slot is fixed by the first file that introduces it, `overload` only changes which @@ -227,10 +249,24 @@ verbatim: but only when `overload` is `false`: if the variable is already set in postmaster's process environment, it is dropped from the resolved set entirely (the child inherits the parent's existing value - unmodified, since `exec()` only *adds* the resolved pairs on top of an - inherited environment). When `overload` is `true`, process environment + unmodified, except for reserved private-key variables). When `overload` + is `true`, process environment is not consulted at all — file values always win. +## Dotenv input limits + +Dotenv sources must be regular files; final symlinks and special files fail +before parsing. Each file is limited to 16 MiB. A resolution pass allows at +most 64 MiB of source bytes, 65,536 assignments, and 64 MiB of parsed names and +values across all dotenv files. Each expanded value is limited to 16 MiB. +Duplicate assignments and metadata count toward these limits before filtering. + +Expansion checks run before appending or retaining substituted values, so a +small substitution chain cannot allocate an unbounded result. Quoting, +multiline values, environment-first substitution, and precedence stay the +same. Syntax errors name the file and error category without including its +contents. Resource-limit failures abort even with `strict: false`. + ## `DOTENV_` filtering and identifier validation - Any raw key beginning with `DOTENV_` (not just the private/public key @@ -252,31 +288,38 @@ verbatim: ## Encrypted-value format -A raw value that does not start with `encrypted:` is passed through -verbatim as opaque bytes (this is how plaintext values reach the child — -no decryption attempted). A value that does start with `encrypted:` has the +Values are first parsed with dotenvy-compatible quoting and variable +substitution rules. A parsed value without `encrypted:` needs no decryption +and is passed through as bytes. A value that starts with `encrypted:` has the following payload base64-decoded and decrypted with `ecies` against each candidate key under the matching `DOTENV_PRIVATE_KEY*` name (comma-separated rotation candidates in `.env.keys` are tried in order; first one that decrypts wins). +Decrypted plaintext and bundle entries are not interpolated. For a plaintext +dotenv value, single quotes preserve `${VAR}` literally; unquoted and +double-quoted values can substitute variables. No value is evaluated as shell +code, and `$(cmd)` does not run a command. + **Lenient base64 decoding:** the payload after `encrypted:` may contain ASCII whitespace (spaces, tabs, newlines, carriage returns). If any is present, it is stripped before decoding, so a value that has been line-wrapped decodes identically to the same value on one line. This matches the wire-compatible behavior for line-wrapped encrypted values and -is exercised directly in `tests/exec_conformance.rs` +is exercised directly in `tests/exec_conformance/main.rs` (`wrapped_base64_ciphertext_decrypts`). `key_var_for` maps an env-file name to the private-key variable it needs: `.env` → `DOTENV_PRIVATE_KEY`; `.env.production` → -`DOTENV_PRIVATE_KEY_PRODUCTION`; non-alphanumeric characters in the -environment suffix become `_` and the whole suffix is upper-cased. A file -name that doesn't start with `.env` is a hard parse error. +`DOTENV_PRIVATE_KEY_PRODUCTION`. The environment suffix must be non-empty +and contain only `[A-Za-z0-9_]` after upper-casing — anything else is a +hard parse error (no lossy mapping: `.env..x` and `.env._x` must never +alias). A file name that doesn't start with `.env` is a hard parse error. ## Per-mode injected variables -**`mode: "env"`.** Decrypts `env_files` through the key ring in `keys`, +**`mode: "env"`.** Decrypts `env_files` and `bundle_files` through the key ring +in `keys`, then exports every resolved `KEY=value` pair directly into the child's environment. No pointer files, no `secrets_dir`. A resolved value containing a NUL byte is a hard error @@ -285,12 +328,14 @@ containing a NUL byte is a hard error closed rather than silently truncating. **`mode: "files"`.** Requires `secrets_dir`. If `verify_ramdisk` is set, -the ramdisk guard (below) runs first; otherwise `secrets_dir` merely has -to exist and be a directory. Each resolved value is written to -`/` with permissions forced to `0600` (via `fchmod` on -the file descriptor after `O_NOFOLLOW | O_CREAT | O_TRUNC` open, so the -permission is set atomically without a TOCTOU window) — unlike `env` mode, -values here may contain NUL; the file is written byte-exact. For each key +the ramdisk guard (below) runs first. The directory must exist and its complete +pathname must be protected from less-trusted replacement. Root and the +effective user are trusted owners; sticky shared parents and trusted symlink +aliases remain supported. The launcher exports the verified canonical path. +Each value is written byte-exact to a fresh exclusive 0600 inode and published +atomically as `/`. Existing handles keep the old contents; +foreign, hardlinked, symlinked, and special existing entries fail closed. +Values may contain NUL. For each key the launcher exports `_FILE` pointing at that path; if the key is also listed in `passthrough`, it is *additionally* exported as a real `=value` env var (and *that* copy is subject to the same NUL-rejection @@ -308,24 +353,26 @@ this mode — it dispatches on whether `sockets` is empty: against running this mode outside systemd). For each key, exports `_FILE=$CREDENTIALS_DIRECTORY/` — no reading, no permission changes; systemd already owns that file. -- **`sockets` non-empty (darwin/launchd fetch path):** requires +- **`sockets` non-empty (local fetch path):** requires `secrets_dir`; runs the ramdisk guard if `verify_ramdisk` is set. For each key, looks up its socket in `sockets` (missing entry is an error), connects and reads to EOF via the same client path `postmaster fetch` uses, writes the bytes to `/` at `0600`, and exports - `_FILE`. After all keys, exports **both** + `_FILE`. After all keys, also exports `CREDENTIALS_DIRECTORY` set to `secrets_dir` - — unlike the systemd branch, there is no real `LoadCredential` - mechanism on darwin, so the launcher has to tell the consumer that - `secrets_dir` *is* its credentials directory. + so the application can use the same credential-directory convention. + This path is normally used with launchd, but `sockets` selects it on + either supported operating system. ## Fail-closed rules -- **`strict` (default `true`).** In `env`/`files` modes, if any value - fails to decrypt (bad key, wrong key, malformed ciphertext), the whole +- **`strict` (default `true`).** In `env`/`files` modes, if a selected dotenv + value fails to decrypt (bad key, wrong key, malformed ciphertext), the whole exec aborts before the child runs — nothing partial is injected. With - `strict: false`, an undecryptable value is logged and simply omitted + `strict: false`, an undecryptable value is logged and omitted from the resolved set (never served as an error string or empty value). + Bundle entries must authenticate regardless of `strict`. `--verify-keys` + also rejects skipped dotenv values when `strict` is false. - **NUL in an environment value** is refused in `env` mode and for `passthrough` values in `files` mode (see above); in `files` mode's primary write path (the pointer-file contents), NUL is not restricted @@ -335,6 +382,10 @@ this mode — it dispatches on whether `sockets` is empty: serve, and fails closed with `": server sent zero bytes (refused to serve); failing closed"` rather than writing an empty credential file. +- **16 MiB read cap.** Config JSON, bundle JSON, and credential fetch payloads + are capped at 16 MiB by `read_capped`; oversized payloads fail. Dotenv + sources have the separate byte, assignment, and expansion limits described + above. Private-key files use the `dotenvy` streaming parser without that cap. - **Missing `$CREDENTIALS_DIRECTORY`** in `credentials` mode's systemd branch fails closed rather than silently exporting nothing. - **Private keys never come from the Nix store.** A `{"file": …}` key @@ -344,21 +395,29 @@ this mode — it dispatches on whether `sockets` is empty: - **Keys file permissions and ownership.** `KeyRing::load` opens the keys file with `O_NOFOLLOW` and `fstat`s the fd to verify: no group/world access (`mode & 0o077 == 0`), and owned by the current - euid. A world-readable or symlinked keys file fails closed. -- **External binary verification.** On macOS, `from_keychain` verifies - the code signature of `/usr/bin/security` via `codesign -v` before - invoking it. On Linux, external binaries are verified as regular files - owned by root (uid 0) and not world-writable. + euid. A world-readable or symlinked keys file fails closed. On macOS, + runtime loading and file-source setup rechecks also reject ACL grants that let + principals other than root or the effective user read or modify the file. + These checks do not change the source file's ACL. +- **External binary verification.** Keychain access uses the + Security.framework API in-process — no external binary is invoked for + it. The external binaries postmaster does invoke (`/usr/bin/id`, + `/sbin/mount`, `/usr/bin/hdiutil` on macOS) are verified first: + `codesign -v` on macOS; on Linux, verified as regular files owned by + root (uid 0) with no group or other write permissions. Linux `id` lookup + resolves system aliases, verifies the target and its directory ancestry, + then invokes that resolved target. This includes the NixOS system profile. - **`verify_ramdisk` (darwin ramdisk guard).** When set, before any plaintext is written the launcher runs two checks: it shells out to `/sbin/mount` and requires the configured mount point to appear as an `hfs` filesystem, then runs `hdiutil info` and requires the device's `image-path` to start with `ram://` (confirming RAM backing, not a - file-backed image). It then `stat`s `secrets_dir` and requires it to - exist, be a directory, and be owned by the launcher's own effective - uid. Either check failing refuses to write plaintext to what might be - persistent disk, with an error pointing at `postmaster-ramdisk` - health. + file-backed image). It opens `secrets_dir` without following a + final-component symlink and checks the pinned inode's ownership and + backing device. The directory must be lexically beneath the mount point + and use the verified RAM device, so an intermediate symlink cannot + redirect plaintext onto persistent storage. Pruning, writes, cleanup, + and the monitor retain that same directory handle. ## Extensibility boundary @@ -407,16 +466,15 @@ with external secret-management tooling that materializes a `{"credential": "postmaster-myapp"}`. AWS tooling owns IAM, network I/O, and retrieval; postmaster inherits systemd's local credential access control. -- **macOS Keychain → `{"keychain": ""}`.** No external tooling - needed beyond what's already documented for `key.keychainService` - (Operational notes) — this is the existing source, not a new - composition, but the one to reach for on darwin when a file or - `LoadCredential` isn't a fit. +- **macOS Keychain → `{"keychain": ""}`.** Use + `postmaster setup` to seed the required accounts under that service name. + Postmaster reads those items through Security.framework. See + [Key provisioning](../getting-started/key-provisioning.md#strategy-d-macos-keychain). ## Conformance -`tests/exec_conformance.rs` is the executable form of this document: -metacharacter-laden values stay inert across all three modes, +`tests/exec_conformance/main.rs` is the executable form of this document: +metacharacter-laden values stay inert in `env` mode, process-env-wins-without-overload and overload-reverses-it, rotation with a bogus first key, strict failure refuses to exec, `0600` pointer files and `passthrough`, both `credentials` branches (systemd pointer-only and diff --git a/docs/src/unsafe-code/index.md b/docs/src/unsafe-code/index.md new file mode 100644 index 0000000..869a630 --- /dev/null +++ b/docs/src/unsafe-code/index.md @@ -0,0 +1,51 @@ +# Unsafe code + +Postmaster deliberately allows `unsafe` at the lint level (documented in +`[lints.rust]` in `Cargo.toml`) because it is a syscall-boundary daemon: +peer-credential checks, anti-debug hardening, signal-mask deferral, the +sibling launch monitor (fork + pidfd/kqueue liveness), and the systemd +socket-activation contract cannot be expressed in safe Rust. Darwin extended +ACL access uses narrow libc bindings as well. +This section documents every approved site. + +## Policy + +Every `unsafe` block requires: + +1. A SAFETY comment at the site covering every UB vector +2. Minimal scope — the smallest possible unsafe block +3. Safe wrappers first — rustix (raw syscalls, no libc FFI) on Linux; + libc only where the platform's stable ABI *is* libc (Darwin) +4. Documentation in this section (registry entry + page) +5. Tests exercising the mitigation where the platform allows + +## Registry + +| Location | Platform | Purpose | Page | +|----------|----------|---------|------| +| `launcher.rs` (TerminationGuard: block/block_input/input_pending/restore_mask/Drop) | macOS, Linux | Defer termination across plaintext writes and no-echo input; restore terminal settings before pending signal delivery | [signal-deferral](./signal-deferral.md) | +| `launcher.rs` (fork(2)) | macOS, Linux | Fork the sibling monitor before exec — the single libc FFI call on Linux (doctrine exception) | [monitor](./monitor.md) | +| `monitor.rs` (signal mask/wait ops, pidfd+poll / kqueue, `_exit`/`exit_group`, raw stderr write) | macOS, Linux | Sibling monitor: synchronous stop consumption, liveness watch, cleanup on every death path | [monitor](./monitor.md) | +| `server.rs` (`peer_euid`) | macOS | Peer credential check via `getpeereid(2)` | [macos-libc-boundary](./macos-libc-boundary.md) | +| `server.rs` (`harden_process`) | macOS, release only | `PT_DENY_ATTACH` anti-debug hardening | [macos-libc-boundary](./macos-libc-boundary.md) | +| `secret_files/acl.rs` | macOS | Inspect directory and key-file ACL grants; clear new private-file ACLs | [macos-libc-boundary](./macos-libc-boundary.md#extended-acls) | +| `test_util/pty.rs` | all, test-only | Create and own pseudo-terminal descriptors for input restoration tests | [signal-deferral](./signal-deferral.md#tests) | +| `server.rs` (socket activation) | Linux | `UnixListener::from_raw_fd` on systemd-inherited sockets | [systemd-fd-ownership](./systemd-fd-ownership.md) | +| `keys/source.rs`, `keys/env.rs`, `keys/provisioning/mod.rs` (test modules) | all, test-only | `set_var`/`remove_var` (unsafe on edition 2024) | [test-env-mutation](./test-env-mutation.md) | + +Note what is NOT in the inventory: `mlockall`, `setrlimit(Core, 0)`, and +`set_dumpable(NotDumpable)` hardening all use **safe** rustix wrappers. + +## Adding Unsafe code + +1. **Exhaust safe alternatives** — rustix first; is there a safe way at all? +2. **Justify in the platform note** — why this platform has no safe route +3. **Minimize scope** — smallest possible unsafe block +4. **Mitigate all UB vectors** — each one named in the SAFETY comment +5. **Add to this section** — registry entry + a page following this format +6. **Write tests** — verify the mitigations work (or document why untestable) +7. **Get review** — unsafe requires explicit approval + +Postmaster decrypts at launch and wipes its key ring and resolved buffers +before `execvp`. A memory-safety bug can expose those buffers or invalidate +cleanup, so each unsafe boundary needs a specific justification. diff --git a/docs/src/unsafe-code/macos-libc-boundary.md b/docs/src/unsafe-code/macos-libc-boundary.md new file mode 100644 index 0000000..a7a4ee6 --- /dev/null +++ b/docs/src/unsafe-code/macos-libc-boundary.md @@ -0,0 +1,92 @@ +# macOS libc boundary + +On Darwin the stable kernel ABI *is* libc, so these calls have no +raw-syscall route (contrast with Linux, where rustix's `linux_raw` +backend avoids libc FFI except `fork(2)`). This page covers peer checks, anti- +debug hardening, and extended ACLs; the launcher's signal-mask guard and the +sibling monitor's +kqueue/signal ops share the same justification and live on their own +pages ([signal deferral](./signal-deferral.md), +[sibling launch monitor](./monitor.md)). + +## getpeereid — peer credential check + +### Location + +```text +src/server.rs — fn peer_euid (macOS cfg only) +``` + +### Purpose + +The credential socket must only answer the service user. On Linux the +daemon reads peer credentials with `SO_PEERCRED` (safe rustix); Darwin +has no `SO_PEERCRED`, so the equivalent is `getpeereid(2)` via libc. + +### UB vectors and mitigations + +| Vector | Description | Mitigation | +|--------|-------------|------------| +| Out-param types | `getpeereid` writes a `uid_t` and a `gid_t` | Out-params are exactly `libc::uid_t`/`libc::gid_t` | +| fd validity | The socket fd must stay valid for the call | Borrowed from `stream` for the call's duration only | + +### Remaining risks + +`getpeereid` establishes *same-euid*, not *same-process*: any process +running as the service user passes. That is an accepted residual of the +UID-based peer model (see the threat model), not a defect of this +wrapper. + +## PT_DENY_ATTACH — anti-debug hardening + +### Location + +```text +src/server.rs — fn harden_process (macOS cfg, release builds only) +``` + +### Purpose + +The ptrace-from-peers half of Linux's `PR_SET_DUMPABLE`: deny debugger +attachment to the daemon. Compiled only under `not(debug_assertions)`; +`[profile.release]` sets `debug-assertions = false` by default. Enabling debug +assertions, including through a profile environment override, disables this +call. A failed attach-denial request is logged. + +### UB vectors and mitigations + +| Vector | Description | Mitigation | +|--------|-------------|------------| +| Bad arguments | `ptrace` is variadic-ish FFI | `PT_DENY_ATTACH` takes no pointer arguments: null addr, zero data — the documented invocation | +| Debug-build denial | Attaching a debugger in dev must stay possible | `#[cfg(not(debug_assertions))]` gate | + +## Tests + +The peer check is exercised wherever the daemon integration tests run on +macOS. `PT_DENY_ATTACH` cannot be meaningfully unit-tested (success +means a subsequent attach fails); its release-only gating is pinned by +`debug-assertions = false` in `[profile.release]` and verified by +release-profile clippy in the standard battery. + +## Extended ACLs + +`src/secret_files/acl.rs` binds the Darwin ACL and membership APIs that rustix +does not expose. Mode bits alone do not restrict extended ACL grants on macOS. +Directory checks reject grants to principals other than root or the effective +user that permit replacement or inherited reads of fresh files. Fresh private +files have their ACLs cleared before plaintext writes. +Runtime key-file loading and file-source setup rechecks use the same +descriptor-based inspection to reject untrusted read or mutation grants without +changing the source ACL. Root and the effective user remain trusted principals. + +The wrapper owns each ACL and qualifier allocation and frees it once with +`acl_free`. Entry pointers borrow the live ACL; output pointers have initialized +storage and stay valid through each call. Qualifiers use Darwin's fixed +16-byte UUID layout and are compared with UUIDs resolved for trusted users. +Descriptor borrows keep the file open throughout each call. Failures return +errors before plaintext is read or written. + +Native tests install replacement and inheritance grants in private fixtures, +verify rejection, and check that published files have no extended entries. +Key-file tests cover read/write grants, trusted-user grants, read-only modes, +and repeated runtime loads and file-source setup rechecks without ACL mutation. diff --git a/docs/src/unsafe-code/monitor.md b/docs/src/unsafe-code/monitor.md new file mode 100644 index 0000000..86075e9 --- /dev/null +++ b/docs/src/unsafe-code/monitor.md @@ -0,0 +1,151 @@ +# Sibling launch monitor + +A sibling process watches the service until it exits. +It forwards stop signals, escalates to SIGKILL after a 250 ms grace, and +removes secret files after exit, a crash, or `kill -9`. It scrubs projected +environment pairs but retains the launcher's original environment. + +## Lifecycle + +```mermaid +sequenceDiagram + participant L as Launcher (parent) + participant M as Monitor (fork-child) + participant S as Service (exec'd parent) + + L->>L: block stop signals, materialize, wipe ring and resolved buffers + L->>M: fork() + Note over M: scrub projected pairs, retain original environment, keep mask blocked + L->>S: restore mask, execvp becomes service + loop poll tick + M->>S: liveness (pidfd+poll / kqueue NOTE_EXIT) + M->>M: stop signal pending? (sigpending then sigwait) + end + alt stop signal (TERM/INT/HUP/QUIT) + M->>S: forward the signal + Note over M,S: bounded grace (250 ms) + alt service exits within the grace + M->>M: cleanup plaintext files, exit 0 + else grace expires + M->>S: SIGKILL + M->>M: cleanup plaintext files, exit 0 + end + else service death (exit, crash, kill -9) + M->>M: cleanup plaintext files, exit 0 + end +``` + +## Location + +```text +src/monitor.rs — the monitor loop, liveness watches, signal ops, exit +src/launcher.rs — the fork(2) site and both TerminationGuard legs (macOS + Linux) +Unsafe blocks: fork(2) (libc, both platforms); rustix `runtime` + kernel_sigprocmask/kernel_sigwait (Linux); libc pthread_sigmask/ + sigpending/sigwait/kqueue/kevent/_exit (macOS); + OwnedFd::from_raw_fd (macOS kqueue fd); BorrowedFd::borrow_raw (stderr) +``` + +## Purpose + +The sibling monitor forwards stop signals and attempts plaintext cleanup +after service exit. After +validation, plaintext writes, and zeroization of the key ring and resolved +buffers, and before `execvp`, +the launcher `fork()`s. The parent restores its +pre-guard signal mask and execs the service (MainPID unchanged); the +fork-child becomes the monitor: it keeps the four termination signals +blocked for life, consumes them synchronously (sigpending/sigwait — no +handlers anywhere), forwards stops to the service, escalates to SIGKILL +after a 250 ms grace (a single global security policy, deliberately not +configurable), watches liveness (pidfd+poll on Linux, kqueue +`EVFILT_PROC`/`NOTE_EXIT` on macOS, `kill(pid, 0)` only as fallback), and +runs `cleanup_written` before exiting — on stop, on natural exit, on +`kill -9`, and crashes. The monitor consumes signals synchronously; it +does not install signal handlers. + +The scrub does not erase the monitor's original process environment. +Private keys supplied through environment variables can remain there for +the monitor's lifetime. Use a non-environment key source to avoid that +exposure. See [Private-key environment variables](../architecture/threat-model.md#private-key-environment-variables). + +## Why unsafe + +- **`fork(2)` has no rustix wrapper** (a deliberate rustix omission), so + it is a direct libc call on both platforms. On Linux this is the + **single libc FFI call on the exec path** — an explicit, review-gated + exception to the "rustix linux_raw / no libc FFI on Linux" doctrine. + Everything else on the Linux leg is rustix. +- **Linux signal masking and synchronous consumption** use rustix's + experimental runtime API (`kernel_sigprocmask`, `kernel_sigwait`, + `kernel_sigpending`, `exit_group`) — rustix's experimental, doc-hidden + API for libc-like runtimes. It is the only rustix route to signal masks + (there is no `rustix::process::sigprocmask`), and taking it avoids libc + signal FFI on Linux. Cargo.lock pins the exact rustix; an update that + changes this unstable API fails the build loudly, never silently. The + documented hazard class (a libc in the process reserves some signals) + does not apply: the mask set holds only TERM/INT/HUP/QUIT/PIPE, none of + which any libc reserves (glibc reserves 32/33). +- **Darwin has no raw-syscall ABI** and no `sigtimedwait` at all, so the + macOS leg uses libc for `pthread_sigmask`, `sigpending`, `sigwait`, + `kqueue`/`kevent`, and `_exit` — the same libc-signal family already on + this boundary, plus kqueue. rustix's `runtime` module does not exist + off Linux (it is `linux_raw_sys`-typed), and rustix's stable API has no + signal-mask or sigwait wrappers on any platform. +- `OwnedFd::from_raw_fd` (kqueue fd) and `BorrowedFd::borrow_raw(2)` + (monitor diagnostics) are fd-ownership assertions of the same kind as + the systemd socket boundary. + +rustix 1.x provides +`pidfd_open`/`pidfd_send_signal` (Linux-only) and `poll`, so the pidfd +leg needs no fallback in practice; `kill(pid, 0)` polling is kept only +for kernels without `pidfd_open` (< 5.3) and for kqueue failure. An +`ESRCH` from `pidfd_open`, from `kevent` registration, or from +`kill(pid, 0)` is race-free "definitely gone" and short-circuits to +cleanup (on macOS, xnu drops exited procs from the pid table before they +are reaped, so NOTE_EXIT registration on an already-exited service fails +`ESRCH` — handled as death, not as a fallback trigger). + +rustix 1.1.6 exports the experimental API as `runtime_448b8ad740e2a26f`. +The launcher and monitor import it as `runtime`. + +## UB vectors and mitigations + +| Vector | Description | Mitigation | +|--------|-------------|------------| +| Fork in a threaded process | The child inherits locked malloc/stdio state | The production launcher is single-threaded at fork. The monitor first scrubs and frees projected env pairs; this exception requires that single-threaded parent. Test children pass an empty pair list. The loop then uses the syscall set documented in `monitor.rs`, without allocation or stdio locks, and exits via `_exit`/`exit_group` | +| Invalid `sigset_t` | Uninitialized set passed to sigwait/sigpending | `KernelSigSet::empty()` (rustix) / `zeroed()` + `sigemptyset` (libc) | +| Blocking sigwait hang | `sigwait` blocks until a set member is pending | Called only after `sigpending` shows a member pending — single-threaded, so nothing else can dequeue it first | +| Mask clobber | Restoring a mask never captured | Linux guard stores `None` on block failure (logged); restore then no-ops | +| Mask leak to the service | Service inheriting blocked termination signals | The parent restores the saved mask before `execvp` (explicit call + `Drop` on early-Err paths); the fork-child's guard is never dropped (`monitor::run` diverges, `_exit` runs no destructors), so the monitor keeps the mask for life | +| Wrong-fd ownership | Closing an fd not owned | `from_raw_fd` wraps a fresh `kqueue()` result exactly once; `borrow_raw(2)` never closes and never outlives the call (an absent stderr just fails the write with EBADF) | +| PID reuse | Signals/liveness hitting a recycled PID | pidfd pins the process: `poll` fires at exit (zombie-proof) and `pidfd_send_signal` cannot hit a recycled PID. `ESRCH` anywhere is treated as race-free death. Residual: the macOS stop-forward path uses plain `kill(2)` (Darwin has no pidfd) — a bounded exposure, accepted in the threat model | +| Zombie blindness | `kill(pid, 0)` succeeds on zombies | pidfd/kqueue are the primary mechanisms precisely because they fire at exit, not at reap; polling is fallback-only and documented | +| Handler unsoundness | Non-reentrant work in signal context | Eliminated by design — there are no signal handlers; consumption is synchronous in the loop | + +## Remaining risks + +| Risk | Likelihood | Impact | +|------|------------|--------| +| rustix `runtime` API changes in a future rustix | Low (lockfile-pinned; build fails loudly at update time) | Build breakage, not a runtime defect | +| Monitor dies before the service | Monitor failure or external termination | Cleanup falls to integration-provided `ExecStopPost`, ramdisk teardown, and next-launch `prune_stale` | +| Job-control stop (SIGTSTP) of the monitor's process group | Interactive sessions only | The monitor suspends with the service; cleanup waits for continuation — backstops remain | +| Service unkillable in D-state after SIGKILL | Kernel pathology | The monitor's post-SIGKILL death wait is unbounded by design (abandoning cleanup is worse); the manager's own escalation path still applies | +| Polling fallback on a pre-5.3 kernel | Legacy kernels only | Zombie-blindness until the parent reaps (systemd reaps promptly); PID-reuse exposure as documented | + +## Tests + +Each fork-based `monitor::tests` case runs in an isolated test process so +other tests cannot race native-library initialization with fork callbacks. +The tests fork the real monitor loop in a real fork-child against +real service processes (deterministic; grace/poll injectable; no env +mutation): natural `kill -9` death → cleanup + exit; TERM to the monitor +→ forwarded (service dies by TERM, proving no escalation) → cleanup + +exit; a TERM-ignoring forked service (`SIG_IGN` + `pause`) → SIGKILL only +after the grace → cleanup + exit; env-mode (no fd, empty names) → exit on +service death. The TERM-ignoring child acknowledges readiness through a +pipe after installing `SIG_IGN`; it uses only async-signal-safe calls after +fork. The parent waits for that acknowledgement before starting the monitor. +The exec integration suites +(`tests/exec_check.rs`, `tests/exec_conformance/`) exercise the full +fork+exec path and assert the post-exit cleanup contract. diff --git a/docs/src/unsafe-code/signal-deferral.md b/docs/src/unsafe-code/signal-deferral.md new file mode 100644 index 0000000..5661170 --- /dev/null +++ b/docs/src/unsafe-code/signal-deferral.md @@ -0,0 +1,94 @@ +# Signal deferral (TerminationGuard) + +While Postmaster decrypts and injects, termination +signals are blocked to protect the plaintext-write window. The launcher +restores the captured mask before exec. Masking failures are logged and +leave the write window unguarded. + +## Location + +```text +src/launcher.rs — struct TerminationGuard (macOS and Linux legs) +Blocks: block()/block_input() (sigmask), input_pending(), restore_mask(), Drop +``` + +## Purpose + +On macOS, plaintext secret files persist on the ramdisk until +explicitly removed, so a SIGTERM landing *during* the plaintext-write +window would leave material on disk with no cleanup. `TerminationGuard` +blocks SIGTERM/SIGINT/SIGHUP/SIGQUIT (`monitor::STOP_SIGNALS`) from +just after config validation until the fork/exec at the end of the +window when masking succeeds. A masking failure is logged and leaves +the window unguarded. SIGKILL cannot be blocked. + +At the end of the window the launcher forks the sibling monitor (see +[Sibling launch monitor](./monitor.md)), which **inherits the blocked +mask and keeps it for life** — the fork-child's guard is never dropped +(the monitor entry point diverges and exits via `_exit`/`exit_group`, +running no destructors). The parent calls `restore_mask()` before +`execvp` so the service starts with a clean signal state. + +Setup reuses the guard while reading secrets from a terminal. `block_input()` +also blocks SIGTSTP, so suspension cannot hand back a terminal with echo disabled. +Terminal reads use nonblocking stdin, including buffered and noncanonical +input. Noncanonical reads temporarily use `VMIN=1` and `VTIME=0`, so an idle +read does not look like EOF. The loop checks pending signals while polling. +Failed or interrupted reads flush unread terminal input before restoring +terminal settings, stdin flags, and the saved signal mask. Successful reads +retain queued values. Prompt writes return errors, allowing restoration even +when stderr fails. Setup refuses terminal input if masking fails. +Redirected input keeps stdin's existing buffer and normal signal +behavior. Linux uses rustix's raw signal APIs; Darwin uses libc. + +## Why unsafe + +Raw signal-mask operations — `pthread_sigmask` on Darwin (whose stable +kernel ABI is libc), `rt_sigprocmask` via rustix's `runtime` module on +Linux — are invisible to Rust's type system: a wrong mask or an invalid +`sigset_t` is undefined behavior the compiler cannot reject. The +pre-fork guard shares its platform notes with the monitor page: the +rustix `runtime` API is experimental (lockfile-pinned), and the mask set +holds only standard signals no libc reserves. + +## UB vectors and mitigations + +| Vector | Description | Mitigation | +|--------|-------------|------------| +| Invalid `sigset_t` | Uninitialized set passed to the mask call | `zeroed()` (valid empty representation) then `sigemptyset` on Darwin; `KernelSigSet::empty()` on Linux | +| Dangling pointers | set/old must outlive each call | Locals live for the full block; no pointers escape | +| Thread-model mismatch | `sigprocmask` is unspecified in multithreaded processes | `pthread_sigmask` form on Darwin; on Linux the launcher is single-threaded at this point (worker threads exist only in serve mode) | +| libc-reserved signals | Masking a signal a libc reserves is UB (rustix `runtime` safety note) | The set holds only TERM/INT/HUP/QUIT, plus TSTP for input — none reserved (glibc reserves 32/33) | +| Mask clobber | Restoring a mask never captured | Both legs are Option-shaped and store `None` on block failure (logged); restore then no-ops | +| Mask leak to the service | Service inheriting blocked termination signals | Mask restored before `execvp` on every path (explicit + `Drop` on early-Err) — the monitor *wants* the mask and is the only inheritor | + +## Remaining risks + +| Risk | Likelihood | Impact | +|------|------------|--------| +| Kernel/libc signal quirks on future OS versions | Very low | Missed deferral (fail-open to an unguarded write window) | +| Operator sends SIGKILL mid-write | n/a | The monitor has not been forked yet. Files can remain until cleanup, RAM-disk destruction, or reboot | + +For the design-level stop semantics the guard feeds into (monitor +forwarding, grace, escalation, cleanup on every death path), see the +threat model's +[plaintext persistence window](../architecture/threat-model.md#plaintext-file-persistence-window-files-mode--mitigated) +section and the [monitor page](./monitor.md). + +## Tests + +The guard's contract is exercised end-to-end by the monitor tests +(`monitor::tests` — every one of them blocks via +`TerminationGuard::block()` before forking the real monitor loop, exactly +mirroring production) and by the exec integration suites +(`tests/exec_check.rs`, `tests/exec_conformance/`). + +Input tests use pseudo-terminals to check hidden single-line and multiline +input, idle noncanonical reads, prompt failures, queued values, and terminal +restoration. Real setup subprocesses cover +initial files, forced rotation, redirected input, and SIGTERM during input. +The interrupted canonical-input test checks what the next terminal reader +receives. +The test-only `openpty` call receives valid output pointers and null optional +settings; each returned descriptor transfers exactly once into an owning +`File`. The harness kills and waits for its child on teardown. diff --git a/docs/src/unsafe-code/systemd-fd-ownership.md b/docs/src/unsafe-code/systemd-fd-ownership.md new file mode 100644 index 0000000..9350c6d --- /dev/null +++ b/docs/src/unsafe-code/systemd-fd-ownership.md @@ -0,0 +1,46 @@ +# systemd fd ownership (Linux) + +On Linux, systemd hands Postmaster sockets as inherited file descriptors. +Postmaster validates the `sd_listen_fds(3)` protocol before adopting them +as owned listeners. + +## Location + +```text +src/server.rs — socket-activation path (Linux cfg only) +``` + +## Purpose + +On Linux, postmaster is socket-activated: the `postmaster-credd.socket` +unit owns the per-(service, key) sockets and the daemon inherits them as +fds `[3, 3+n)`. Serving requires a `UnixListener`, so each inherited fd +is adopted with `UnixListener::from_raw_fd`. + +## Why unsafe + +`from_raw_fd` asserts *ownership*: if the fd were invalid, duplicated +elsewhere, or owned by someone else, the result is double-close / +use-after-close — undefined behavior the compiler cannot check. + +## UB vectors and mitigations + +| Vector | Description | Mitigation | +|--------|-------------|------------| +| Wrong fd | Arbitrary fd adopted by mistake | The `sd_listen_fds(3)` protocol is validated first: `LISTEN_PID` names this process, so fds `[3, 3+n)` are exactly the sockets systemd created for us | +| Double ownership | Some other component also owns the fd | The protocol transfers ownership to this process; nothing else holds these fds | +| fd leak to child | Inherited socket leaking across execvp | `FD_CLOEXEC` is set on the listener immediately after adoption | +| Not-a-socket | Wrong unit passed non-socket fds | `getsockname(2)` mapping to the filesystem path fails closed immediately | + +## Remaining risks + +| Risk | Likelihood | Impact | +|------|------------|--------| +| Misconfigured unit files (wrong `FileDescriptorName`/count) | Low | Fails closed at startup (path mapping), never serves a wrong socket | + +## Tests + +Not exercised on macOS dev hosts (the macOS leg uses `--bind`, which owns +its socket paths directly). The adoption is one line inside a path that +fails closed on every validation error; the daemon's fetch-loop +integration tests cover the serving behavior that follows it. diff --git a/docs/src/unsafe-code/test-env-mutation.md b/docs/src/unsafe-code/test-env-mutation.md new file mode 100644 index 0000000..77e31d0 --- /dev/null +++ b/docs/src/unsafe-code/test-env-mutation.md @@ -0,0 +1,45 @@ +# Test-only environment mutation + +Some tests must change the process environment, +which Rust 2024 marks `unsafe` because it can race other threads. +Every such test holds one shared process-wide lock, so env-mutating +tests can never run — or race — concurrently. + +## Location + +```text +src/test_util.rs — the shared ENV_LOCK itself +src/keys/source.rs (test module) — credential and source-selection tests +src/keys/env.rs (test module) — environment key-loading tests +src/keys/provisioning/mod.rs (test module) — environment provisioning checks +``` + +## Purpose + +Edition 2024 marks `std::env::set_var`/`remove_var` `unsafe`: mutating +the process environment is a data race in a multithreaded process, and +the Rust test harness runs tests in parallel threads of one process. +Several key-source tests must set or clear `DOTENV_PRIVATE_KEY*` / +`POSTMASTER_KEY*` / `CREDENTIALS_DIRECTORY` to exercise source +selection. + +## UB vectors and mitigations + +| Vector | Description | Mitigation | +|--------|-------------|------------| +| Concurrent env access | Two tests mutating/reading env at once | Every call site holds the single process-wide `ENV_LOCK` (`crate::test_util`) for the mutation's full scope | +| Lock-ordering | Multiple env-mutating tests in one binary | One shared mutex for the whole test binary; no nested acquisition | + +Each site carries a SAFETY comment naming the serialization discipline. + +## Why one process-wide lock + +Module-local locks do not exclude tests in other modules. Every test that +mutates the environment, or reads variables another test mutates, must hold +`crate::test_util::ENV_LOCK` for that scope. The lock serializes cooperating +tests; it does not control environment access inside unrelated libraries. + +## Tests + +These sites exist *in* tests; the shared-lock discipline is their +correctness property, exercised by every suite run. diff --git a/flake.nix b/flake.nix index 0c442e2..c483a16 100644 --- a/flake.nix +++ b/flake.nix @@ -1,12 +1,9 @@ { description = '' - postmaster — a standalone, format-neutral local secret - materialization engine. Decrypts encrypted secret inputs at process - launch time and injects them into a child process via environment - variables, files, or systemd credentials, then execvp's the target - binary directly. Supports file-based (.env), HashiCorp Vault, AWS SSM, - and other secret providers as source/custody backends, with Nix, CDK, - Ansible, SaltStack, Puppet, Terraform, and OpenTofu as automation targets. + Postmaster decrypts local secret inputs and delivers values through + environment variables, files, or credentials before execvp replaces the + launcher with the application. Deployment tools generate exec.json and + provide local keys, storage, permissions, and service-manager policy. ''; inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05"; diff --git a/lefthook.yml b/lefthook.yml index 9ba3fd3..9abbeda 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -8,8 +8,14 @@ pre-commit: run: just fmt-check lint: run: just clippy + lint-md: + run: just lint-md pre-push: commands: ci-rust: run: just ci-rust + deny: + run: just deny + audit: + run: just audit diff --git a/licenses/dotenvy-MIT.txt b/licenses/dotenvy-MIT.txt new file mode 100644 index 0000000..11e157d --- /dev/null +++ b/licenses/dotenvy-MIT.txt @@ -0,0 +1,21 @@ +# The MIT License (MIT) + +Copyright (c) 2014 Santiago Lapresta and contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. \ No newline at end of file diff --git a/licenses/ecies-MIT.txt b/licenses/ecies-MIT.txt new file mode 100644 index 0000000..51ab670 --- /dev/null +++ b/licenses/ecies-MIT.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2019-2026 Weiliang Li + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/nixpkgs-package.nix b/nixpkgs-package.nix index 3bec812..6cc8c57 100644 --- a/nixpkgs-package.nix +++ b/nixpkgs-package.nix @@ -7,14 +7,14 @@ # Steps before real submission: # 1. Tag a release in this repo (e.g. v0.1.0) that matches Cargo.toml version. # 2. Replace the placeholder hash with the real one: -# nix-prefetch-url --unpack https://github.com/beardedeagle/envelope/archive/refs/tags/v0.1.0.tar.gz +# nix-prefetch-url --unpack https://github.com/beardedeagle/postmaster/archive/refs/tags/v0.1.0.tar.gz # (or use nix-update / pkgs/by-name update machinery later) # 3. Add yourself to maintainers/maintainer-list.nix if not present. # 4. Set meta.maintainers appropriately. # 5. Run nixpkgs-review and ensure ofborg builds on linux + darwin. # # Notes: -# - The Rust crate lives in the "postmaster/" subdirectory of the repo. +# - The Rust crate lives at the repository root. # - We use cargoLock (preferred when a lockfile exists and there are no git deps). # - No native build inputs needed (pure Rust + rustix; "pure" feature on ecies avoids openssl). @@ -29,21 +29,18 @@ rustPlatform.buildRustPackage rec { src = fetchFromGitHub { owner = "beardedeagle"; - repo = "envelope"; + repo = "postmaster"; rev = "v${version}"; hash = "sha256-PLACEHOLDER"; # update after tagging }; - sourceRoot = "${src.name}/postmaster"; - cargoLock = { - lockFile = src + "/postmaster/Cargo.lock"; - # No outputHashes needed — all dependencies come from crates.io. + lockFile = src + "/Cargo.lock"; }; meta = { description = "postmaster credential bridge: serves decrypted secret values as systemd LoadCredential AF_UNIX sources"; - homepage = "https://github.com/beardedeagle/envelope"; + homepage = "https://github.com/beardedeagle/postmaster"; license = lib.licenses.mit; maintainers = with lib.maintainers; [ ]; # replace when you have an entry mainProgram = "postmaster"; diff --git a/package.nix b/package.nix index 99d3f51..5378756 100644 --- a/package.nix +++ b/package.nix @@ -3,8 +3,8 @@ let cargoToml = lib.importTOML ./Cargo.toml; # Build a rustPlatform from the latest stable rust-overlay toolchain. - # nixos-25.05's rustPlatform ships rustc 1.86.0, too old for edition 2024 - # + let-chains (requires >= 1.96.1). rust-overlay provides newer toolchains + # nixos-25.05's rustPlatform ships rustc 1.86.0, below Cargo.toml's + # Rust 1.99.1 minimum. rust-overlay provides newer toolchains # independent of the nixpkgs channel. rustPlatform = makeRustPlatform { rustc = rust-bin.stable.latest.rust; @@ -21,6 +21,7 @@ rustPlatform.buildRustPackage { fileset = lib.fileset.unions [ ./Cargo.toml ./Cargo.lock + ./licenses ./src ]; }; @@ -29,15 +30,14 @@ rustPlatform.buildRustPackage { meta = { description = cargoToml.package.description; longDescription = '' - postmaster is a dependency-lean Rust daemon (edition 2024; pure-Rust - crypto with no openssl, no async runtime) that serves decrypted - values as systemd LoadCredential AF_UNIX sources (with equivalent - support under nix-darwin). It enables encrypted .env files to be - treated as ordinary, world-readable Nix store artifacts while - guaranteeing that plaintext secrets only ever appear inside - unit-private unswappable credential ramfs. + Postmaster decrypts local dotenv and bundle inputs and delivers values + through environment variables, files, or systemd credentials before + replacing the launcher with the application. It also serves credentials + over local Unix sockets. Deployments provide storage, access controls, + and service-manager hardening. Encrypted artifacts can be public; + private keys and plaintext entries need separate protection. ''; - homepage = "https://github.com/beardedeagle/envelope"; + homepage = "https://github.com/beardedeagle/postmaster"; license = lib.licenses.mit; mainProgram = "postmaster"; platforms = lib.platforms.linux ++ lib.platforms.darwin; diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 05e6ca1..da44fa7 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -2,3 +2,4 @@ channel = "stable" profile = "minimal" components = ["rustfmt", "clippy"] +targets = ["x86_64-unknown-linux-gnu"] diff --git a/src/aad.rs b/src/aad.rs new file mode 100644 index 0000000..29a10c5 --- /dev/null +++ b/src/aad.rs @@ -0,0 +1,90 @@ +//! Entry-name-bound ECIES bundle envelopes. +//! +//! The wire layout is an uncompressed secp256k1 point (65 bytes), nonce +//! (16 bytes), authentication tag (16 bytes), then ciphertext. +// Portions adapted from ecies/rs. Copyright (c) 2019-2026 Weiliang Li. +// MIT license: see licenses/ecies-MIT.txt. + +use aes_gcm::aead::{AeadInOut, KeyInit, Nonce, Tag}; +use aes_gcm::{AesGcm, aes::Aes256, aes::cipher::consts::U16}; +use zeroize::Zeroizing; + +type Cipher = AesGcm; + +/// Decrypt an ECIES envelope with the caller's exact additional authenticated data. +/// +/// Returns plaintext only after authentication succeeds, or `None` for an +/// invalid key, malformed envelope, or authentication failure. +pub(crate) fn decrypt(secret: &[u8], envelope: &[u8], aad: &[u8]) -> Option>> { + let (ephemeral, payload) = envelope.split_at_checked(65)?; + let (nonce, payload) = payload.split_at_checked(16)?; + let (tag, ciphertext) = payload.split_at_checked(16)?; + let secret = ecies::SecretKey::parse_slice(secret).ok()?; + let ephemeral = ecies::PublicKey::parse_slice(ephemeral, None).ok()?; + let key = Zeroizing::new(ecies::utils::decapsulate(&ephemeral, &secret, false).ok()?); + let cipher = Cipher::new_from_slice(&key[..]).ok()?; + let nonce = Nonce::::try_from(nonce).ok()?; + let tag = Tag::::try_from(tag).ok()?; + let mut plaintext = Zeroizing::new(ciphertext.to_vec()); + cipher + .decrypt_inout_detached(&nonce, aad, plaintext.as_mut_slice().into(), &tag) + .ok()?; + Some(plaintext) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used)] +mod tests { + use super::decrypt; + use serde::Deserialize; + + #[derive(Deserialize)] + struct Vector { + aad_hex: String, + ciphertext_hex: String, + plaintext_hex: String, + } + + fn vectors() -> Vec { + // Fixed ECIES envelopes pin the wire format and entry-name authentication. + serde_json::from_str(include_str!("aad/vectors.json")).unwrap() + } + + #[test] + fn decrypts_existing_fork_envelopes_byte_exactly() { + for vector in vectors() { + let ciphertext = hex::decode(vector.ciphertext_hex).unwrap(); + let aad = hex::decode(vector.aad_hex).unwrap(); + let expected = hex::decode(vector.plaintext_hex).unwrap(); + assert_eq!( + decrypt(&[0x11; 32], &ciphertext, &aad).unwrap().as_slice(), + expected + ); + if aad.is_empty() { + assert_eq!(ecies::decrypt(&[0x11; 32], &ciphertext).unwrap(), expected); + } else { + assert!(decrypt(&[0x11; 32], &ciphertext, b"").is_none()); + } + assert!(decrypt(&[0x11; 32], &ciphertext, b"wrong-entry").is_none()); + assert!(decrypt(&[0x22; 32], &ciphertext, &aad).is_none()); + } + } + + #[test] + fn malformed_and_tampered_envelopes_fail_closed() { + let vector = vectors().remove(1); + let ciphertext = hex::decode(vector.ciphertext_hex).unwrap(); + let aad = hex::decode(vector.aad_hex).unwrap(); + for len in 0..ciphertext.len() { + assert!(decrypt(&[0x11; 32], &ciphertext[..len], &aad).is_none()); + } + for i in 0..ciphertext.len() { + let mut changed = ciphertext.clone(); + changed[i] ^= 1; + assert!(decrypt(&[0x11; 32], &changed, &aad).is_none(), "byte {i}"); + } + for key in [vec![], vec![0x11; 31], vec![0; 32], vec![0xff; 32]] { + assert!(decrypt(&key, &ciphertext, &aad).is_none()); + } + } +} diff --git a/src/aad/vectors.json b/src/aad/vectors.json new file mode 100644 index 0000000..865ae84 --- /dev/null +++ b/src/aad/vectors.json @@ -0,0 +1,22 @@ +[ + { + "aad_hex": "", + "ciphertext_hex": "04e1f84068c5393739e00975958030f5d3d84b293ad251faff1834c6356018ab3f0397b905f2ef5854a32d99a48d6f8eed001708ba61dabad3517253dd4fbd3acd709ee1c06a162bdec0e1fc9643b984327afffc2c624eba46dab7f80419727de85704a27e9f21", + "plaintext_hex": "6c6567616379" + }, + { + "aad_hex": "534543524554", + "ciphertext_hex": "0499c1196596fc690653b4ead8717a6724263c8de7b1343209c122449d278a8e052709a129652b91a5b31336b3eff9981d1a248ef53ebf48eb2ec6a288de8ebde20c98c863fad6ec3c0c5af2cb8532168f742e58bea3495da5427c0c3c41a3db4a894e564e987dafc322aaf8d8f06d0f", + "plaintext_hex": "6578697374696e672062756e646c65" + }, + { + "aad_hex": "42494e415259", + "ciphertext_hex": "04b259c62d4e1d2b6f81f13966287f4967d94e82d9675b192217ed7e9440c4db5d6182ab0321bd5f59c745c3b22dd1f0b871c961cbc65e9a9b4d029a73d9d06fa687eabd3efe5e634c85bcce1fad68155a4b5075a792f640f1cf44c893069adf2f07f0f303", + "plaintext_hex": "00ff800a" + }, + { + "aad_hex": "454d505459", + "ciphertext_hex": "04ce8c1eb88b4f167ea05c0fd9f4125fc9abc9d552479d22178bcdf813674d38ebb2105880f5c41a2b85a118cf09e24684c7c7ad4061da0b97a055e4a9a3c8d58fd162e634288caf1379e99749ab73368423221113f1910e6a6f786b63bf8c5d77", + "plaintext_hex": "" + } +] diff --git a/src/bundle.rs b/src/adapter/bundle.rs similarity index 60% rename from src/bundle.rs rename to src/adapter/bundle.rs index 57a2e60..b1d6bf7 100644 --- a/src/bundle.rs +++ b/src/adapter/bundle.rs @@ -1,19 +1,19 @@ -//! `postmaster_bundle` adapter: a neutral JSON container for encrypted -//! secrets that doesn't pretend to be an `.env` file. +//! `postmaster_bundle` adapter for structured, encrypted JSON inputs. //! //! The bundle format is a JSON file with: //! - `format`: must be `"postmaster.bundle"` (fail closed on unknown) //! - `version`: integer, must be `1` -//! - `profile`: optional public selection metadata (not a secret) +//! - `profile`: optional public metadata, not used for key selection //! - `suite`: mandatory crypto suite identifier (must match the ECIES path) //! - `recipients`: array of `{ id, public_key }` — public routing metadata //! - `entries`: map of key name → `{ encoding, ciphertext }` //! //! All fields are public metadata except `ciphertext`, which is -//! encrypted and authenticated. Entries use the same identifier rule -//! as `.env`-derived keys: `[A-Za-z_][A-Za-z0-9_]*`. - -#![allow(missing_docs, missing_debug_implementations)] +//! encrypted and authenticated. Each entry's ciphertext is additionally +//! bound to its key name as AES-GCM additional authenticated data (AAD): +//! a ciphertext cut from one entry and pasted under another name fails +//! decryption. Entries use the same identifier +//! rule as `.env`-derived keys: `[A-Za-z_][A-Za-z0-9_]*`. use std::path::Path; @@ -22,7 +22,7 @@ use base64::engine::general_purpose::STANDARD as BASE64; use serde::Deserialize; use zeroize::Zeroizing; -use crate::keys::{KeyRing, is_ident}; +use crate::keys::{KeyRing, is_ident, is_private_key_var_name}; /// The top-level bundle container. #[derive(Deserialize, Debug)] @@ -32,7 +32,7 @@ pub struct Bundle { pub format: String, /// Must be `1`. pub version: u32, - /// Optional public selection metadata (not a secret). + /// Optional public metadata, not used to select keys or entries. #[serde(default)] pub profile: Option, /// Mandatory crypto suite identifier. @@ -44,14 +44,15 @@ pub struct Bundle { pub entries: std::collections::BTreeMap, } -/// A recipient in the bundle: public routing metadata used to select -/// local private key material. +/// Public recipient metadata, parsed but not used for key selection. +/// Resolution uses the fixed `POSTMASTER_KEY` variable. #[derive(Deserialize, Debug)] #[serde(deny_unknown_fields)] pub struct Recipient { /// Public identifier for this recipient (e.g., `"host:api-01"`). pub id: String, - /// Compressed secp256k1 public key (hex-encoded). + /// Public-key metadata, conventionally compressed secp256k1 hex. + /// Parsed as a string; not used for decryption. pub public_key: String, } @@ -59,9 +60,8 @@ pub struct Recipient { #[derive(Deserialize, Debug)] #[serde(deny_unknown_fields)] pub struct BundleEntry { - /// Either `"utf8"` or `"bytes"`. `env` projection rejects bytes that - /// cannot become a POSIX environment value; `files` and `credentials` - /// preserve byte-exact values. + /// Either `"utf8"` or `"bytes"`. UTF-8 is validated during resolution. + /// Env projection rejects NUL bytes; files preserve byte-exact values. pub encoding: Encoding, /// Base64-encoded ECIES ciphertext. pub ciphertext: String, @@ -71,11 +71,19 @@ pub struct BundleEntry { #[derive(Deserialize, Debug, Clone, Copy, PartialEq, Eq)] #[serde(rename_all = "lowercase")] pub enum Encoding { + /// UTF-8 string value, validated during resolution in every mode. Utf8, + /// Raw byte value; files preserve it and env projection rejects NUL. Bytes, } -/// Parse a bundle JSON file from raw bytes. +/// The only supported crypto suite: ECIES (secp256k1, HKDF-SHA256, +/// AES-256-GCM) with the entry name bound as AES-GCM additional +/// authenticated data. Ciphertexts that do not authenticate with that entry +/// name are rejected during decryption. +const SUITE: &str = "ecies-secp256k1-hkdf-sha256-aes-256-gcm-entry-aad"; + +/// Parse a bundle JSON file, rejecting invalid metadata and reserved key names. pub fn parse_bundle(raw: &[u8], path: &Path) -> Result { let bundle: Bundle = serde_json::from_slice(raw).map_err(|e| format!("{}: {e}", path.display()))?; @@ -93,9 +101,9 @@ pub fn parse_bundle(raw: &[u8], path: &Path) -> Result { bundle.version )); } - if bundle.suite != "ecies-secp256k1-hkdf-sha256-aes-256-gcm" { + if bundle.suite != SUITE { return Err(format!( - "{}: unsupported suite {:?} (expected ecies-secp256k1-hkdf-sha256-aes-256-gcm)", + "{}: unsupported suite {:?} (expected {SUITE})", path.display(), bundle.suite )); @@ -107,6 +115,12 @@ pub fn parse_bundle(raw: &[u8], path: &Path) -> Result { path.display() )); } + if is_private_key_var_name(name) { + return Err(format!( + "{}: key {name:?} is reserved for private-key provisioning", + path.display() + )); + } } Ok(bundle) } @@ -136,21 +150,35 @@ pub fn resolve_bundle( .decode(&entry.ciphertext) .map_err(|_| format!("{}: {name} is not valid base64", bundle_path.display()))?, ); + // AAD = the entry name: a ciphertext pasted under a different entry fails + // authentication here. let mut decrypted: Option>> = None; for sk in candidates { - if let Ok(pt) = ecies::decrypt(&sk[..], &ciphertext) { - decrypted = Some(Zeroizing::new(pt)); + if let Some(pt) = crate::aad::decrypt(&sk[..], &ciphertext, name.as_bytes()) { + decrypted = Some(pt); break; } } match decrypted { - Some(pt) => out.push((name.clone(), pt, entry.encoding)), + Some(pt) => { + // `utf8` is a promise the bundle makes to env-mode + // consumers: validate it at the trust boundary and fail + // closed — invalid bytes must never flow into an + // environment value. `bytes` entries stay byte-exact. + if entry.encoding == Encoding::Utf8 && std::str::from_utf8(&pt).is_err() { + return Err(format!( + "{}: {name} declares utf8 but is not valid UTF-8", + bundle_path.display() + )); + } + out.push((name.clone(), pt, entry.encoding)); + } None => { let _ = ciphertext; // zeroize on drop + // No candidate count in the error text. return Err(format!( - "{}: no key under {var} decrypts {name} ({} candidate(s) tried)", - bundle_path.display(), - candidates.len() + "{}: no key under {var} decrypts {name}", + bundle_path.display() )); } } @@ -162,6 +190,7 @@ pub fn resolve_bundle( #[allow(clippy::unwrap_used, clippy::panic, unused_qualifications)] mod tests { use super::*; + use crate::test_util::aad_fixture::encrypt; use std::collections::BTreeMap; fn test_pk_hex() -> String { @@ -186,7 +215,7 @@ mod tests { format: "postmaster.bundle".into(), version: 1, profile: Some("test".into()), - suite: "ecies-secp256k1-hkdf-sha256-aes-256-gcm".into(), + suite: SUITE.into(), recipients: vec![Recipient { id: "test".into(), public_key: test_pk_hex(), @@ -195,9 +224,9 @@ mod tests { } } - fn enc(value: &str) -> String { + fn enc(name: &str, value: &str) -> String { let pk = hex::decode(test_pk_hex()).unwrap(); - let ct = ecies::encrypt(&pk, value.as_bytes()).unwrap(); + let ct = encrypt(&pk, value.as_bytes(), name.as_bytes()); BASE64.encode(ct) } @@ -206,7 +235,7 @@ mod tests { let raw = serde_json::json!({ "format": "wrong", "version": 1, - "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm", + "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm-entry-aad", "recipients": [], "entries": {} }); @@ -223,7 +252,7 @@ mod tests { let raw = serde_json::json!({ "format": "postmaster.bundle", "version": 99, - "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm", + "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm-entry-aad", "recipients": [], "entries": {} }); @@ -257,7 +286,7 @@ mod tests { let raw = serde_json::json!({ "format": "postmaster.bundle", "version": 1, - "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm", + "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm-entry-aad", "recipients": [], "entries": { "BAD.KEY": { "encoding": "utf8", "ciphertext": "dGVzdA==" } @@ -276,7 +305,7 @@ mod tests { let raw = serde_json::json!({ "format": "postmaster.bundle", "version": 1, - "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm", + "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm-entry-aad", "recipients": [], "entries": {}, "unknown_field": "should fail" @@ -292,7 +321,7 @@ mod tests { #[test] fn resolve_bundle_decrypts_entries() { - let ct = enc("hello-bundle"); + let ct = enc("SECRET", "hello-bundle"); let bundle = make_bundle(vec![("SECRET", &ct, Encoding::Utf8)]); let ring = crate::keys::tests::make_test_ring(); let resolved = resolve_bundle(&bundle, &ring, Path::new("/test")).unwrap(); @@ -302,14 +331,27 @@ mod tests { assert_eq!(resolved[0].2, Encoding::Utf8); } + #[test] + fn resolve_bundle_rejects_relocated_ciphertext() { + // A ciphertext encrypted under one entry name must not decrypt under another. + let ct = enc("REAL", "top-secret"); + let bundle = make_bundle(vec![("FAKE", &ct, Encoding::Utf8)]); + let ring = crate::keys::tests::make_test_ring(); + let err = resolve_bundle(&bundle, &ring, Path::new("/test")).unwrap_err(); + assert!(err.contains("no key under"), "{err}"); + } + #[test] fn resolve_bundle_fails_on_wrong_key() { let other_sk = "22".repeat(32); let other_sk_bytes = hex::decode(&other_sk).unwrap(); let other_sk = ecies::SecretKey::parse_slice(&other_sk_bytes).unwrap(); let other_pk = ecies::PublicKey::from_secret_key(&other_sk); - let ct = BASE64 - .encode(ecies::encrypt(&other_pk.serialize_compressed(), b"unreachable").unwrap()); + let ct = BASE64.encode(encrypt( + &other_pk.serialize_compressed(), + b"unreachable", + b"SECRET", + )); let bundle = make_bundle(vec![("SECRET", &ct, Encoding::Utf8)]); let ring = crate::keys::tests::make_test_ring(); let err = resolve_bundle(&bundle, &ring, Path::new("/test")).unwrap_err(); @@ -320,7 +362,7 @@ mod tests { fn resolve_bundle_handles_bytes_encoding() { let binary_val = b"\x00\x01\x02\xff"; let pk = hex::decode(test_pk_hex()).unwrap(); - let ct = BASE64.encode(ecies::encrypt(&pk, binary_val).unwrap()); + let ct = BASE64.encode(encrypt(&pk, binary_val, b"TLS_KEY")); let bundle = make_bundle(vec![("TLS_KEY", &ct, Encoding::Bytes)]); let ring = crate::keys::tests::make_test_ring(); let resolved = resolve_bundle(&bundle, &ring, Path::new("/test")).unwrap(); @@ -328,10 +370,32 @@ mod tests { assert_eq!(resolved[0].2, Encoding::Bytes); } + #[test] + fn resolve_bundle_rejects_invalid_utf8_when_declared_utf8() { + // An entry declaring `encoding: "utf8"` whose plaintext is not + // valid UTF-8 must fail closed; the same plaintext under + // `encoding: "bytes"` stays byte-exact. + let invalid = b"\xff\xfe"; + let pk = hex::decode(test_pk_hex()).unwrap(); + let ct = BASE64.encode(encrypt(&pk, invalid, b"GREETING")); + let ring = crate::keys::tests::make_test_ring(); + + let bundle = make_bundle(vec![("GREETING", &ct, Encoding::Utf8)]); + let err = resolve_bundle(&bundle, &ring, Path::new("/test")).unwrap_err(); + assert!( + err.contains("GREETING declares utf8 but is not valid UTF-8"), + "{err}" + ); + + let bundle = make_bundle(vec![("GREETING", &ct, Encoding::Bytes)]); + let resolved = resolve_bundle(&bundle, &ring, Path::new("/test")).unwrap(); + assert_eq!(&resolved[0].1[..], &invalid[..]); + } + #[test] fn resolve_bundle_multiple_entries() { - let ct1 = enc("value1"); - let ct2 = enc("value2"); + let ct1 = enc("KEY_A", "value1"); + let ct2 = enc("KEY_B", "value2"); let bundle = make_bundle(vec![ ("KEY_A", &ct1, Encoding::Utf8), ("KEY_B", &ct2, Encoding::Utf8), @@ -345,4 +409,34 @@ mod tests { assert_eq!(resolved[1].0, "KEY_B"); assert_eq!(&resolved[1].1[..], b"value2"); } + + #[test] + fn resolve_bundle_requires_a_postmaster_key_entry() { + // A ring containing only dotenv keys must report the missing bundle key. + let ct = enc("SECRET", "unreachable"); + let bundle = make_bundle(vec![("SECRET", &ct, Encoding::Utf8)]); + let env_only_ring = KeyRing::from_pairs( + [( + "DOTENV_PRIVATE_KEY".to_string(), + zeroize::Zeroizing::new("22".repeat(32)), + )], + &[crate::adapter::KeyNaming::Env], + ) + .unwrap(); + let err = resolve_bundle(&bundle, &env_only_ring, Path::new("/test")).unwrap_err(); + assert!( + err.contains("key ring has no POSTMASTER_KEY entry"), + "{err}" + ); + } + + #[test] + fn resolve_bundle_rejects_invalid_base64() { + // Malformed base64 in a ciphertext field is a hard parse error naming the + // entry, not a decrypt failure. + let bundle = make_bundle(vec![("SECRET", "!!!not-base64!!!", Encoding::Utf8)]); + let ring = crate::keys::tests::make_test_ring(); + let err = resolve_bundle(&bundle, &ring, Path::new("/test")).unwrap_err(); + assert!(err.contains("SECRET is not valid base64"), "{err}"); + } } diff --git a/src/adapter.rs b/src/adapter/mod.rs similarity index 50% rename from src/adapter.rs rename to src/adapter/mod.rs index 5b75ddc..e97342f 100644 --- a/src/adapter.rs +++ b/src/adapter/mod.rs @@ -1,25 +1,19 @@ //! Adapter enum for key-naming conventions. //! -//! Different input adapters (`.env` files, `postmaster_bundle`, etc.) have -//! different conventions for how private keys are named, how metadata keys -//! are filtered, and how artifact filenames map to key variable names. This -//! enum encapsulates those conventions so the core key-loading and -//! resolution logic is adapter-neutral. +//! Dotenv and bundle inputs have different key names, metadata filters, and +//! filename mappings. `KeyNaming` keeps those rules together for loading and +//! resolution. //! -//! An enum (not a trait) is used deliberately: the set of adapters is small -//! and security-critical. Exhaustive match ensures every call site handles -//! every adapter at compile time — adding a variant is a deliberate act -//! that forces all code paths to acknowledge it. +//! Exhaustive matches make new adapter variants a compile-time obligation +//! for each dispatch site. -#![allow(missing_docs, missing_debug_implementations)] +pub mod bundle; use std::path::Path; /// The key-naming convention for a secret input adapter. /// -/// Adding a variant is a deliberate act: every match on this enum must -/// handle the new variant or the code will not compile. This is the -/// security boundary — no adapter can silently slip through unhandled. +/// Each dispatch match must handle every adapter variant. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum KeyNaming { /// The `.env` file adapter. Uses `DOTENV_PRIVATE_KEY[_]` as its @@ -27,8 +21,7 @@ pub enum KeyNaming { /// `.env.production` → `DOTENV_PRIVATE_KEY_PRODUCTION`. Env, /// The `postmaster_bundle` adapter. Uses `POSTMASTER_KEY` as its - /// key variable naming (no per-environment suffix — the bundle's - /// `profile` field handles environment selection). No metadata + /// key variable naming, regardless of filename or `profile`. No metadata /// prefix (the bundle format is structured JSON, not flat key-value). Bundle, } @@ -56,8 +49,7 @@ impl KeyNaming { /// Map an artifact filename to the key variable name it needs. /// `.env` → `DOTENV_PRIVATE_KEY`, `.env.production` → /// `DOTENV_PRIVATE_KEY_PRODUCTION`. Bundle files map to a single - /// key variable regardless of filename (the `profile` field inside - /// the bundle handles environment selection). + /// key variable regardless of filename. `profile` does not select a key. pub fn key_var_for(self, artifact_path: &Path) -> Result { match self { KeyNaming::Env => { @@ -74,16 +66,16 @@ impl KeyNaming { let env = rest.strip_prefix('.').ok_or_else(|| { format!("{base}: env files must follow the `.env[.]` convention") })?; - let suffix: String = env - .chars() - .map(|c| { - if c.is_ascii_alphanumeric() { - c.to_ascii_uppercase() - } else { - '_' - } - }) - .collect(); + // Reject anything outside [A-Za-z0-9_]: such characters would sanitize + // to '_', making distinct filenames collide on the same key variable + // (`.env..x` ≡ `.env._x`). Letters fold to upper case, the dotenvx + // convention. + if env.is_empty() || !env.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') { + return Err(format!( + "{base}: environment name must be non-empty [A-Za-z0-9_] only" + )); + } + let suffix: String = env.chars().map(|c| c.to_ascii_uppercase()).collect(); Ok(format!("{}_{}", self.key_prefix(), suffix)) } KeyNaming::Bundle => Ok(self.key_prefix().into()), @@ -98,3 +90,57 @@ impl KeyNaming { } } } + +#[cfg(test)] +#[allow(clippy::unwrap_used)] +mod tests { + use super::*; + + #[test] + fn key_var_for_env_mapping() { + assert_eq!( + KeyNaming::Env.key_var_for(Path::new("/x/.env")).unwrap(), + "DOTENV_PRIVATE_KEY" + ); + assert_eq!( + KeyNaming::Env + .key_var_for(Path::new("/x/.env.production")) + .unwrap(), + "DOTENV_PRIVATE_KEY_PRODUCTION" + ); + assert_eq!( + KeyNaming::Env + .key_var_for(Path::new("/x/.env.staging_v2")) + .unwrap(), + "DOTENV_PRIVATE_KEY_STAGING_V2" + ); + } + + #[test] + fn key_var_for_requires_the_dot_env_convention() { + // Dotenv inputs must follow the .env[.] naming convention. + assert!(KeyNaming::Env.key_var_for(Path::new("no-dot-env")).is_err()); + } + + #[test] + fn key_var_for_rejects_aliasing_names() { + // Reject lossy names that could alias another file's key variable. + assert!(KeyNaming::Env.key_var_for(Path::new("/x/.env..x")).is_err()); + assert!(KeyNaming::Env.key_var_for(Path::new("/x/.env.-x")).is_err()); + assert!(KeyNaming::Env.key_var_for(Path::new("/x/.env.")).is_err()); + assert_eq!( + KeyNaming::Env.key_var_for(Path::new("/x/.env._x")).unwrap(), + "DOTENV_PRIVATE_KEY__X" + ); + } + + #[test] + fn key_var_for_bundle_is_constant() { + assert_eq!( + KeyNaming::Bundle + .key_var_for(Path::new("/x/anything.json")) + .unwrap(), + "POSTMASTER_KEY" + ); + } +} diff --git a/src/cli/help.rs b/src/cli/help.rs new file mode 100644 index 0000000..597812a --- /dev/null +++ b/src/cli/help.rs @@ -0,0 +1,93 @@ +//! Help text constants for the postmaster CLI. + +/// Top-level help text shown by `postmaster --help` or `postmaster help`. +pub const HELP_TOP: &str = "postmaster — standalone secret materialization engine\n\n\ +USAGE:\n \ +postmaster --config [--bind] [--allow-nonroot]\n \ +postmaster fetch \n \ +postmaster exec --config [--check] [--verify-keys] -- [args…]\n \ +postmaster setup --config [--recheck] [--unattended] [--force] [--keys-dir ]\n \ +postmaster cleanup --config \n \ +postmaster help [subcommand]\n \ +postmaster --version\n\n\ +SUBCOMMANDS:\n \ +exec Decrypt secrets and exec a child process with them injected\n \ +fetch Fetch a single secret from a postmaster daemon socket\n \ +setup Verify environment, create keys directory, seed keychain (idempotent)\n \ +cleanup Remove plaintext secret files from secrets_dir (ExecStopPost)\n \ +help Show help for a subcommand or this message\n\n\ +OPTIONS:\n \ +--config Configuration file (required for serve, exec, setup, cleanup)\n \ +--bind (serve) Bind listener sockets even if not socket-activated\n \ +--allow-nonroot (serve) Allow any UID when peer_user is unset\n \ +--check (exec) Validate config shape only, no decryption or exec\n \ +--verify-keys (exec) Preflight key freshness check before exec\n \ +--recheck (setup) Verification only, no creation or modification\n \ +--unattended (setup) Non-interactive mode for automation (fail closed)\n \ +--force (setup) Re-create or re-seed even if already correct\n \ +--keys-dir

(setup) Override default keys directory path\n \ +--version, -V Print version and exit\n \ +--help, -h Show this help message\n"; + +/// Help text for the `exec` subcommand. +pub const HELP_EXEC: &str = "postmaster exec — decrypt secrets and exec a child process\n\n\ +USAGE:\n \ +postmaster exec --config [--check] [--verify-keys] -- [args…]\n\n\ +Resolves configured inputs, projects values through environment variables,\n\ +files, or credential pointers, and replaces the launcher with the command.\n\n\ +OPTIONS:\n \ +--config Exec config JSON (required)\n \ +--check Validate config shape only, no decryption, no exec\n \ +--verify-keys Preflight: fail unless EVERY value in every env file decrypts;\n \ +under `strict:false` any skipped/undecryptable value also aborts\n \ +the launch (fail-closed)\n \ +-- Everything after `--` is the child argv (required unless --check)\n\n\ +The config selects mode (env/files/credentials) and its required fields.\n\ +Env and files modes need key sources and artifact paths. Credentials mode\n\ +uses existing credential files or configured local sockets. See\n\ +docs/src/reference/launcher-contract.md for the full contract.\n"; + +/// Help text for the `fetch` subcommand. +pub const HELP_FETCH: &str = "postmaster fetch — fetch a secret from a daemon socket\n\n\ +USAGE:\n \ +postmaster fetch \n\n\ +Connects to a local postmaster AF_UNIX socket, reads its configured secret\n\ +to EOF, and writes the bytes to stdout. The credentials-mode launcher uses\n\ +the same client path when sockets are configured. Available on Linux and macOS.\n\n\ +The socket path must be a single relative or absolute path to the AF_UNIX\n\ +socket created by `postmaster --config `.\n"; + +/// Help text for the `setup` subcommand. +pub const HELP_SETUP: &str = "postmaster setup — provision and verify local key sources\n\n\ +USAGE:\n \ +postmaster setup --config [--recheck] [--unattended] [--force] [--keys-dir ]\n\n\ +Verifies platform prerequisites, creates the keys directory with 0700\n\ +permissions, verifies or creates keys files with 0600, optionally seeds\n\ +keychain items (macOS, interactive), and validates the environment.\n\n\ +Steps already satisfied are skipped. Use --unattended for automated runs;\n\ +it fails if operator input is required. Required Keychain accounts are\n\ +deduplicated before prompting, preserving first-seen input order.\n\n\ +OPTIONS:\n \ +--config Exec config JSON (required)\n \ +--recheck Verification only — no creation or modification\n \ +--unattended Non-interactive mode for automation (fail closed, no prompts)\n \ +--non-interactive Alias for --unattended\n \ +--force Re-create or re-seed even if already correct\n \ +--keys-dir Override the default keys directory\n\n\ +Default keys directory: /var/lib/postmaster (Linux),\n\ +~/Library/Application Support/postmaster (macOS).\n"; + +/// Help text for the `cleanup` subcommand. +pub const HELP_CLEANUP: &str = "postmaster cleanup — remove secret files from secrets_dir\n\n\ +USAGE:\n \ +postmaster cleanup --config \n\n\ +Reads the exec config, extracts secrets_dir, and removes all regular files\n\ +in that directory. Intended for ExecStopPost in systemd or equivalent\n\ +lifecycle hooks in other service managers.\n\n\ +Does not decrypt. A non-empty directory without a .postmaster-managed\n\ +sentinel is left untouched. The marker identifies the managed directory,\n\ +not individual files. Keep one secrets_dir per service. Empty or missing\n\ +directories need no cleanup. Secret-file removal failures retain the marker\n\ +and return an error so cleanup can be retried.\n\n\ +OPTIONS:\n \ +--config Exec config JSON (required)\n"; diff --git a/src/cli/mod.rs b/src/cli/mod.rs new file mode 100644 index 0000000..7c2ecb4 --- /dev/null +++ b/src/cli/mod.rs @@ -0,0 +1,585 @@ +//! CLI parsing (`Invocation`, `parse_args`, help text) and the +//! configuration data structures for postmaster's daemon and exec modes. +//! +//! Deployment tools provide JSON configuration containing public paths, +//! key-source names, and projection settings. + +use std::collections::HashMap; +use std::path::PathBuf; + +use serde::Deserialize; + +mod help; + +/// CLI help text, also available through the `crate::config` alias. +pub use help::{HELP_CLEANUP, HELP_EXEC, HELP_FETCH, HELP_SETUP, HELP_TOP}; + +/// Daemon configuration loaded from JSON. Unknown fields are rejected. +#[derive(Deserialize, Debug)] +#[serde(deny_unknown_fields)] +pub struct Config { + /// Where the .env.keys material comes from. + pub keys: KeysSource, + /// Absolute socket path → what to serve on it. + pub credentials: HashMap, +} + +#[derive(Deserialize, Debug)] +#[serde(rename_all = "snake_case")] +/// Where postmaster should obtain its own private keys. +pub enum KeysSource { + /// Name under $CREDENTIALS_DIRECTORY (the daemon's own LoadCredential). + Credential(String), + /// Absolute filesystem path (must not live in the Nix store). + File(PathBuf), +} + +#[derive(Deserialize, Clone, Debug)] +#[serde(deny_unknown_fields)] +/// A single credential mapping served by postmaster. Unknown fields are +/// rejected — same strictness as `Config`. +pub struct Entry { + /// Dotenv input containing encrypted values, plaintext entries, or both. + pub env_file: PathBuf, + /// Which key inside it to serve. + pub key: String, + /// Trusted SHA-256 hashes of the exact dotenv file bytes, as 64-digit hex strings. + /// A hash must match before parsing, interpolation or decryption. + #[serde(deserialize_with = "deserialize_env_file_hashes")] + pub env_file_sha256: Vec<[u8; 32]>, + /// Allow this user as well as root to fetch the credential. + /// Enforced even when `--allow-nonroot` is set. + #[serde(default)] + pub peer_user: Option, +} + +fn deserialize_env_file_hashes<'de, D>(deserializer: D) -> Result, D::Error> +where + D: serde::Deserializer<'de>, +{ + Vec::::deserialize(deserializer)? + .into_iter() + .map(|value| { + let mut hash = [0; 32]; + hex::decode_to_slice(value, &mut hash).map_err(|_| { + serde::de::Error::custom("env_file_sha256 requires 64-digit hex hashes") + })?; + Ok(hash) + }) + .collect() +} + +/// Parsed command-line arguments for the `serve` invocation. +#[derive(Debug)] +pub struct Args { + /// Path to the daemon config JSON file. + pub config: PathBuf, + /// Bind listener sockets even when not socket-activated. + pub bind: bool, + /// Allow non-root peers to connect (dev escape hatch; never overrides + /// a configured `peer_user` ACL). + pub allow_nonroot: bool, +} + +/// The parsed top-level invocation selected from CLI arguments. +#[derive(Debug)] +pub enum Invocation { + /// `postmaster --config [--bind] [--allow-nonroot]`: + /// run the credential daemon (socket-activated on Linux, bind on macOS). + Serve(Args), + /// `postmaster fetch `: connect to a running daemon + /// socket and write the decrypted bytes to stdout. + Fetch(PathBuf), + /// `postmaster exec --config [--check] [--verify-keys]` + /// `-- `: decrypt + inject per the launcher contract, then + /// execvp argv. See launcher.rs. + Exec { + /// Path to the exec config JSON. + config: PathBuf, + /// Validate config shape only — no decryption, no exec. + check: bool, + /// Preflight: fail unless EVERY value in every env file + /// decrypts. Catches stale keys from a previous rotation cycle + /// that are valid hex but no longer match the ciphertext; under + /// `strict: false` any skipped/undecryptable value also aborts + /// the launch (fail-closed). + verify_keys: bool, + /// Child argv — everything after `--` on the command line. + argv: Vec, + }, + /// `postmaster setup --config [--recheck] [--unattended] + /// [--force] [--keys-dir ]`: verify platform prerequisites, + /// create keys directory with correct permissions, optionally seed + /// keychain items, and validate the environment. Idempotent — skips + /// steps that are already correct. `--recheck` re-verifies without + /// creating or modifying anything. + Setup { + /// Path to the exec config JSON. + config: PathBuf, + /// Verification only — no creation or modification. + recheck: bool, + /// Non-interactive mode for automation (fail closed, no prompts). + unattended: bool, + /// Re-create or re-seed even if already correct. + force: bool, + /// Override the default keys directory path. + keys_dir: Option, + }, + /// `postmaster cleanup --config `: remove all secret files + /// from the secrets_dir configured in the exec config. Intended for + /// `ExecStopPost` in systemd or equivalent lifecycle hooks in other + /// service managers. Does not decrypt — only removes files that + /// postmaster would have written. Bulk removal is refused for a + /// non-empty directory lacking the `.postmaster-managed` sentinel. + Cleanup { + /// Path to the exec config JSON. + config: PathBuf, + }, + /// Print help text and exit successfully. + Help(Option), + /// Print version and exit successfully. + Version, +} + +/// Crate version, resolved at compile time from `CARGO_PKG_VERSION`. +pub const VERSION: &str = env!("CARGO_PKG_VERSION"); + +/// Consume the value of a value-taking option, rejecting another flag as +/// the value: `--config --check` must not parse `"--check"` as the +/// config path. +fn option_value( + it: &mut std::iter::Peekable>, + flag: &str, +) -> Result { + match it.next() { + None => Err(format!("error: {flag} requires a path")), + Some(v) if v.starts_with('-') => Err(format!( + "error: {flag} requires a path, got flag `{v}` (missing value?)" + )), + Some(v) => Ok(v), + } +} + +/// Parse command-line arguments from `std::env::args()`. +pub fn parse_args() -> Result { + parse_args_from(std::env::args().skip(1)) +} + +/// Parse command-line arguments from a provided iterator. Kept simple +/// with no external dependencies (no clap). +pub fn parse_args_from(args: impl IntoIterator) -> Result { + let mut it = args.into_iter().peekable(); + + // No args: print help and fail + if it.peek().is_none() { + return Err(format!( + "{HELP_TOP}\n\nerror: no subcommand or --config provided" + )); + } + + match it.peek().map(String::as_str) { + // Global flags that work before any subcommand + Some("--help") | Some("-h") => { + it.next(); + if it.next().is_some() { + return Err("error: --help does not take arguments".into()); + } + Ok(Invocation::Help(None)) + } + Some("--version") | Some("-V") => { + it.next(); + if it.next().is_some() { + return Err("error: --version does not take arguments".into()); + } + Ok(Invocation::Version) + } + Some("help") => { + it.next(); + let sub = it.next(); + if it.next().is_some() { + return Err( + "error: `help` takes at most one argument (the subcommand name)".into(), + ); + } + Ok(Invocation::Help(sub)) + } + Some("fetch") => { + it.next(); + match it.next() { + // Every subcommand takes --help/-h. + Some(a) if a == "--help" || a == "-h" => Ok(Invocation::Help(Some("fetch".into()))), + Some(path) => { + if it.next().is_some() { + return Err( + "error: fetch takes exactly one argument (the socket path)".into() + ); + } + Ok(Invocation::Fetch(PathBuf::from(path))) + } + None => Err("error: fetch requires a socket path".into()), + } + } + Some("exec") => { + it.next(); + let mut config = None; + let mut check = false; + let mut verify_keys = false; + let mut argv: Vec = Vec::new(); + while let Some(a) = it.next() { + match a.as_str() { + "--config" => { + config = Some(PathBuf::from(option_value(&mut it, "--config")?)); + } + "--check" => check = true, + "--verify-keys" => verify_keys = true, + "--help" | "-h" => return Ok(Invocation::Help(Some("exec".into()))), + "--" => { + argv = it.collect(); + break; + } + other => { + return Err(format!( + "error: exec: unknown option `{other}`\n\n{HELP_EXEC}" + )); + } + } + } + if check { + if !argv.is_empty() { + return Err("error: exec --check does not accept a command after `--`".into()); + } + } else if argv.is_empty() { + return Err(format!( + "error: exec: missing command after `--`\n\n{HELP_EXEC}" + )); + } + Ok(Invocation::Exec { + config: config.ok_or("error: exec: missing required --config ")?, + check, + verify_keys, + argv, + }) + } + Some("setup") => { + it.next(); + let mut config = None; + let mut recheck = false; + let mut unattended = false; + let mut force = false; + let mut keys_dir = None; + while let Some(a) = it.next() { + match a.as_str() { + "--config" => { + config = Some(PathBuf::from(option_value(&mut it, "--config")?)); + } + "--recheck" => recheck = true, + "--unattended" | "--non-interactive" => unattended = true, + "--force" => force = true, + "--keys-dir" => { + keys_dir = Some(PathBuf::from(option_value(&mut it, "--keys-dir")?)); + } + "--help" | "-h" => return Ok(Invocation::Help(Some("setup".into()))), + other => { + return Err(format!( + "error: setup: unknown option `{other}`\n\n{HELP_SETUP}" + )); + } + } + } + let config = config.ok_or("error: setup: missing required --config ")?; + Ok(Invocation::Setup { + config, + recheck, + unattended, + force, + keys_dir, + }) + } + Some("cleanup") => { + it.next(); + let mut config = None; + while let Some(a) = it.next() { + match a.as_str() { + "--config" => { + config = Some(PathBuf::from(option_value(&mut it, "--config")?)); + } + "--help" | "-h" => return Ok(Invocation::Help(Some("cleanup".into()))), + other => { + return Err(format!( + "error: cleanup: unknown option `{other}`\n\n{HELP_CLEANUP}" + )); + } + } + } + Ok(Invocation::Cleanup { + config: config.ok_or("error: cleanup: missing required --config ")?, + }) + } + // Serve mode (default, no subcommand keyword) + Some("--config") | Some("--bind") | Some("--allow-nonroot") => { + let mut config = None; + let mut bind = false; + let mut allow_nonroot = false; + while let Some(a) = it.next() { + match a.as_str() { + "--config" => { + config = Some(PathBuf::from(option_value(&mut it, "--config")?)); + } + "--bind" => bind = true, + "--allow-nonroot" => allow_nonroot = true, + "--help" | "-h" => return Ok(Invocation::Help(None)), + other => { + return Err(format!("error: unknown option `{other}`\n\n{HELP_TOP}")); + } + } + } + Ok(Invocation::Serve(Args { + config: config.ok_or("error: missing required --config ")?, + bind, + allow_nonroot, + })) + } + Some(other) => Err(format!( + "error: unknown subcommand `{other}`\n\nTry `postmaster help` for usage.\n" + )), + None => unreachable!("empty args handled above"), + } +} + +#[cfg(test)] +#[allow(unused_qualifications, clippy::panic, clippy::unwrap_used)] +/// Tests for CLI argument parsing. +mod tests { + use super::*; + + fn parse(v: &[&str]) -> Result { + parse_args_from(v.iter().map(ToString::to_string)) + } + + #[test] + fn parse_exec() { + match parse(&[ + "exec", "--config", "/e.json", "--", "/bin/app", "--flag", "x", + ]) { + Ok(Invocation::Exec { + config, + check, + verify_keys, + argv, + }) => { + assert_eq!(config, PathBuf::from("/e.json")); + assert!(!check); + assert!(!verify_keys); + assert_eq!(argv, vec!["/bin/app", "--flag", "x"]); + } + other => panic!("expected Exec, got {other:?}"), + } + } + + #[test] + fn parse_exec_check() { + match parse(&["exec", "--config", "/e.json", "--check"]) { + Ok(Invocation::Exec { + config, + check, + argv, + .. + }) => { + assert_eq!(config, PathBuf::from("/e.json")); + assert!(check); + assert!(argv.is_empty()); + } + other => panic!("expected Exec check, got {other:?}"), + } + } + + #[test] + fn parse_exec_verify_keys() { + match parse(&[ + "exec", + "--config", + "/e.json", + "--verify-keys", + "--", + "/bin/app", + ]) { + Ok(Invocation::Exec { + config, + check, + verify_keys, + argv, + }) => { + assert_eq!(config, PathBuf::from("/e.json")); + assert!(!check); + assert!(verify_keys); + assert_eq!(argv, vec!["/bin/app"]); + } + other => panic!("expected Exec with --verify-keys, got {other:?}"), + } + } + + #[test] + fn parse_exec_requires_command() { + assert!(parse(&["exec", "--config", "/e.json"]).is_err()); + assert!(parse(&["exec", "--config", "/e.json", "--"]).is_err()); + assert!(parse(&["exec", "--config", "/e.json", "--check", "--", "/bin/app"]).is_err()); + } + + #[test] + fn parse_fetch_and_serve_still_work() { + assert!(matches!( + parse(&["fetch", "/s.sock"]), + Ok(Invocation::Fetch(_)) + )); + assert!(matches!( + parse(&["--config", "/c.json", "--bind"]), + Ok(Invocation::Serve(Args { bind: true, .. })) + )); + } + + #[test] + fn parse_help_top_level() { + assert!(matches!(parse(&["--help"]), Ok(Invocation::Help(None)))); + assert!(matches!(parse(&["-h"]), Ok(Invocation::Help(None)))); + } + + #[test] + fn parse_help_subcommand() { + assert!(matches!(parse(&["help"]), Ok(Invocation::Help(None)))); + assert!(matches!( + parse(&["help", "exec"]), + Ok(Invocation::Help(Some(s))) if s == "exec" + )); + assert!(matches!( + parse(&["help", "setup"]), + Ok(Invocation::Help(Some(s))) if s == "setup" + )); + } + + #[test] + fn parse_version() { + assert!(matches!(parse(&["--version"]), Ok(Invocation::Version))); + assert!(matches!(parse(&["-V"]), Ok(Invocation::Version))); + } + + #[test] + fn parse_no_args_fails() { + assert!(parse(&[]).is_err()); + } + + #[test] + fn config_rejects_unknown_fields_in_nested_entry() { + // The nested credential Entry is as strict as the top-level Config — an unknown + // field is a binding bug, not something to silently ignore. + let raw = serde_json::json!({ + "keys": {"file": "/run/postmaster/.env.keys"}, + "credentials": { + "/run/cred.sock": {"env_file": "/nix/store/x/.env", "key": "DB_URL", "bogus": 1} + } + }); + let err = serde_json::from_value::(raw).unwrap_err(); + assert!(err.to_string().contains("unknown field"), "{err}"); + + // A well-formed config still parses. + let raw = serde_json::json!({ + "keys": {"credential": "postmaster-keys"}, + "credentials": { + "/run/cred.sock": {"env_file": "/nix/store/x/.env", "key": "DB_URL", "env_file_sha256": ["0000000000000000000000000000000000000000000000000000000000000000"], "peer_user": "_www"} + } + }); + serde_json::from_value::(raw).unwrap(); + } + + #[test] + fn parse_unknown_subcommand_fails() { + let err = parse(&["bogus"]).unwrap_err(); + assert!(err.contains("unknown subcommand"), "{err}"); + assert!(err.contains("Try `postmaster help`"), "{err}"); + } + + #[test] + fn parse_help_in_exec_subcommand() { + assert!(matches!( + parse(&["exec", "--help"]), + Ok(Invocation::Help(Some(s))) if s == "exec" + )); + } + + #[test] + fn parse_help_in_setup_subcommand() { + assert!(matches!( + parse(&["setup", "--help"]), + Ok(Invocation::Help(Some(s))) if s == "setup" + )); + } + + #[test] + fn parse_setup_flags() { + assert!(matches!( + parse(&["setup", "--config", "/e.json", "--recheck"]), + Ok(Invocation::Setup { recheck: true, .. }) + )); + assert!(matches!( + parse(&["setup", "--config", "/e.json", "--unattended"]), + Ok(Invocation::Setup { + unattended: true, + .. + }) + )); + assert!(matches!( + parse(&["setup", "--config", "/e.json", "--force"]), + Ok(Invocation::Setup { force: true, .. }) + )); + assert!(matches!( + parse(&["setup", "--config", "/e.json", "--keys-dir", "/custom"]), + Ok(Invocation::Setup { keys_dir: Some(p), .. }) if &*p == std::path::Path::new("/custom") + )); + } + + #[test] + fn parse_cleanup() { + assert!(matches!( + parse(&["cleanup", "--config", "/e.json"]), + Ok(Invocation::Cleanup { config }) if &*config == std::path::Path::new("/e.json") + )); + assert!(parse(&["cleanup"]).is_err()); + assert!(parse(&["cleanup", "--config"]).is_err()); + } + + #[test] + fn parse_help_in_cleanup_subcommand() { + assert!(matches!( + parse(&["cleanup", "--help"]), + Ok(Invocation::Help(Some(s))) if s == "cleanup" + )); + } + + #[test] + fn parse_help_in_fetch_subcommand() { + // Fetch accepts --help/-h without treating either flag as a socket path. + assert!(matches!( + parse(&["fetch", "--help"]), + Ok(Invocation::Help(Some(s))) if s == "fetch" + )); + assert!(matches!( + parse(&["fetch", "-h"]), + Ok(Invocation::Help(Some(s))) if s == "fetch" + )); + // The real path still parses. + assert!(matches!( + parse(&["fetch", "/run/pm/s.sock"]), + Ok(Invocation::Fetch(p)) if &*p == std::path::Path::new("/run/pm/s.sock") + )); + } + + #[test] + fn parse_rejects_flag_as_option_value() { + // A value-taking option must not swallow the following flag as its value. + let err = parse(&["exec", "--config", "--check"]).unwrap_err(); + assert!(err.contains("--config"), "{err}"); + assert!(err.contains("--check"), "{err}"); + let err = parse(&["setup", "--keys-dir", "--force", "--config", "/e.json"]).unwrap_err(); + assert!(err.contains("--keys-dir"), "{err}"); + assert!(parse(&["exec", "--config"]).is_err()); + } +} diff --git a/src/config.rs b/src/config.rs deleted file mode 100644 index 33245c9..0000000 --- a/src/config.rs +++ /dev/null @@ -1,928 +0,0 @@ -//! Configuration parsing and data structures for postmaster. -//! -//! The config is generated by the Nix module as JSON. It contains only -//! public information (store paths for ciphertext + key *names*). - -#![allow(missing_docs, missing_debug_implementations)] - -use std::collections::HashMap; -use std::path::{Component, Path, PathBuf}; - -use serde::Deserialize; - -use crate::adapter::KeyNaming; - -/// Full configuration loaded from the JSON file produced by the Nix module. -#[derive(Deserialize, Debug)] -pub struct Config { - /// Where the .env.keys material comes from. - pub keys: KeysSource, - /// Absolute socket path → what to serve on it. - pub credentials: HashMap, -} - -#[derive(Deserialize, Debug)] -#[serde(rename_all = "snake_case")] -/// Where postmaster should obtain its own private keys. -pub enum KeysSource { - /// Name under $CREDENTIALS_DIRECTORY (the daemon's own LoadCredential). - Credential(String), - /// Absolute filesystem path (must not live in the Nix store). - File(PathBuf), -} - -#[derive(Deserialize, Clone, Debug)] -/// A single credential mapping served by postmaster. -pub struct Entry { - /// encrypted env file (a Nix store path; ciphertext is public). - pub env_file: PathBuf, - /// Which key inside it to serve. - pub key: String, - /// Additionally allow this (non-root) user to fetch the credential. - /// Used by the darwin module, where consumers are launchd daemons - /// connecting as their own service user rather than pid 1. - #[serde(default)] - pub peer_user: Option, -} - -#[derive(Debug)] -pub struct Args { - pub config: PathBuf, - pub bind: bool, - pub allow_nonroot: bool, -} - -#[derive(Debug)] -pub enum Invocation { - Serve(Args), - Fetch(PathBuf), - /// `postmaster exec --config [--check] [--verify-keys]` - /// `-- `: decrypt + inject per the launcher contract, then - /// execvp argv. See launcher.rs. - Exec { - config: PathBuf, - check: bool, - /// Preflight: attempt a test decryption of one encrypted value - /// from each env file before proceeding to exec. Catches stale - /// keys from a previous rotation cycle that are valid hex but - /// no longer match the ciphertext (audit finding #4). - verify_keys: bool, - argv: Vec, - }, - /// `postmaster setup --config [--recheck] [--unattended] - /// [--force] [--keys-dir ]`: verify platform prerequisites, - /// create keys directory with correct permissions, optionally seed - /// keychain items, and validate the environment. Idempotent — skips - /// steps that are already correct. `--recheck` re-verifies without - /// creating or modifying anything. - Setup { - config: PathBuf, - recheck: bool, - unattended: bool, - force: bool, - keys_dir: Option, - }, - /// `postmaster cleanup --config `: remove all secret files - /// from the secrets_dir configured in the exec config. Intended for - /// `ExecStopPost` in systemd or equivalent lifecycle hooks in other - /// service managers. Does not decrypt — only removes files that - /// postmaster would have written. - Cleanup { - config: PathBuf, - }, - /// Print help text and exit successfully. - Help(Option), - /// Print version and exit successfully. - Version, -} - -pub const VERSION: &str = env!("CARGO_PKG_VERSION"); - -pub const HELP_TOP: &str = "postmaster — standalone secret materialization engine\n\n\ -USAGE:\n \ -postmaster --config [--bind] [--allow-nonroot]\n \ -postmaster fetch \n \ -postmaster exec --config [--check] [--verify-keys] -- [args…]\n \ -postmaster setup --config [--recheck] [--unattended] [--force] [--keys-dir ]\n \ -postmaster help [subcommand]\n \ -postmaster --version\n\n\ -SUBCOMMANDS:\n \ -exec Decrypt secrets and exec a child process with them injected\n \ -fetch Fetch a single secret from a postmaster daemon socket\n \ -setup Verify environment, create keys directory, seed keychain (idempotent)\n \ -help Show help for a subcommand or this message\n\n\ -OPTIONS:\n \ ---config Configuration file (required for serve, exec, setup)\n \ ---bind (serve) Bind listener sockets even if not socket-activated\n \ ---allow-nonroot (serve) Allow non-root connections (dangerous)\n \ ---check (exec) Validate config shape only, no decryption or exec\n \ ---verify-keys (exec) Preflight key freshness check before exec\n \ ---recheck (setup) Verification only, no creation or modification\n \ ---unattended (setup) Non-interactive mode for automation (fail closed)\n \ ---force (setup) Re-create or re-seed even if already correct\n \ ---keys-dir

(setup) Override default keys directory path\n \ ---version, -V Print version and exit\n \ ---help, -h Show this help message\n"; - -pub const HELP_EXEC: &str = "postmaster exec — decrypt secrets and exec a child process\n\n\ -USAGE:\n \ -postmaster exec --config [--check] [--verify-keys] -- [args…]\n\n\ -Decrypts the configured env files and/or bundle files using the loaded key\n\ -ring, injects the resolved values into the child environment (or writes them\n\ -as files / credential pointers depending on mode), and execs the command.\n\n\ -OPTIONS:\n \ ---config Exec config JSON (required)\n \ ---check Validate config shape only, no decryption, no exec\n \ ---verify-keys Preflight: test-decrypt one value per env file before exec\n \ --- Everything after `--` is the child argv (required unless --check)\n\n\ -The config must specify mode (env/files/credentials), key sources, and\n\ -artifact paths. See docs/src/launcher-contract.md for the full contract.\n"; - -pub const HELP_FETCH: &str = "postmaster fetch — fetch a secret from a daemon socket\n\n\ -USAGE:\n \ -postmaster fetch \n\n\ -Connects to a running postmaster daemon's AF_UNIX socket, requests the\n\ -default secret, and writes the decrypted bytes to stdout. Used internally\n\ -by the credentials-mode launcher on macOS (launchd) to pull secrets from\n\ -the daemon into the RAM disk.\n\n\ -The socket path must be a single relative or absolute path to the AF_UNIX\n\ -socket created by `postmaster --config `.\n"; - -pub const HELP_SETUP: &str = "postmaster setup — verify environment and create key material\n\n\ -USAGE:\n \ -postmaster setup --config [--recheck] [--unattended] [--force] [--keys-dir ]\n\n\ -Verifies platform prerequisites, creates the keys directory with 0700\n\ -permissions, verifies or creates keys files with 0600, optionally seeds\n\ -keychain items (macOS, interactive), and validates the environment.\n\n\ -Idempotent — each step checks whether the target state is already present\n\ -and correct, and skips if it is. Safe to run on every converge cycle.\n\n\ -OPTIONS:\n \ ---config Exec config JSON (required)\n \ ---recheck Verification only — no creation or modification\n \ ---unattended Non-interactive mode for automation (fail closed, no prompts)\n \ ---force Re-create or re-seed even if already correct\n \ ---keys-dir Override the default keys directory\n\n\ -Default keys directory: /var/lib/postmaster (Linux),\n\ -~/Library/Application Support/postmaster (macOS).\n"; - -pub const HELP_CLEANUP: &str = "postmaster cleanup — remove secret files from secrets_dir\n\n\ -USAGE:\n \ -postmaster cleanup --config \n\n\ -Reads the exec config, extracts secrets_dir, and removes all regular files\n\ -in that directory. Intended for ExecStopPost in systemd or equivalent\n\ -lifecycle hooks in other service managers.\n\n\ -Does not decrypt — only removes files that postmaster would have written.\n\ -Safe to run even if the directory is already empty or does not exist.\n\n\ -OPTIONS:\n \ ---config Exec config JSON (required)\n"; - -pub const USAGE: &str = "usage: postmaster --config [--bind] [--allow-nonroot]\n postmaster fetch \n postmaster exec --config [--check] [--verify-keys]\n postmaster exec --config [--verify-keys] -- [args…]\n postmaster setup --config [--recheck] [--unattended] [--force] [--keys-dir ]\n postmaster cleanup --config "; - -/// Parse command line arguments. Kept simple with no external deps. -pub fn parse_args() -> Result { - parse_args_from(std::env::args().skip(1)) -} - -pub fn parse_args_from(args: impl IntoIterator) -> Result { - let mut it = args.into_iter().peekable(); - - // No args: print help and fail - if it.peek().is_none() { - return Err(format!( - "{HELP_TOP}\n\nerror: no subcommand or --config provided" - )); - } - - match it.peek().map(String::as_str) { - // Global flags that work before any subcommand - Some("--help") | Some("-h") => { - it.next(); - if it.next().is_some() { - return Err("error: --help does not take arguments".into()); - } - Ok(Invocation::Help(None)) - } - Some("--version") | Some("-V") => { - it.next(); - if it.next().is_some() { - return Err("error: --version does not take arguments".into()); - } - Ok(Invocation::Version) - } - Some("help") => { - it.next(); - let sub = it.next(); - if it.next().is_some() { - return Err( - "error: `help` takes at most one argument (the subcommand name)".into(), - ); - } - Ok(Invocation::Help(sub)) - } - Some("fetch") => { - it.next(); - let path = it.next().ok_or("error: fetch requires a socket path")?; - if it.next().is_some() { - return Err("error: fetch takes exactly one argument (the socket path)".into()); - } - Ok(Invocation::Fetch(PathBuf::from(path))) - } - Some("exec") => { - it.next(); - let mut config = None; - let mut check = false; - let mut verify_keys = false; - let mut argv: Vec = Vec::new(); - while let Some(a) = it.next() { - match a.as_str() { - "--config" => { - config = Some(PathBuf::from( - it.next().ok_or("error: --config requires a path")?, - )); - } - "--check" => check = true, - "--verify-keys" => verify_keys = true, - "--help" | "-h" => return Ok(Invocation::Help(Some("exec".into()))), - "--" => { - argv = it.collect(); - break; - } - other => { - return Err(format!( - "error: exec: unknown option `{other}`\n\n{HELP_EXEC}" - )); - } - } - } - if check { - if !argv.is_empty() { - return Err("error: exec --check does not accept a command after `--`".into()); - } - } else if argv.is_empty() { - return Err(format!( - "error: exec: missing command after `--`\n\n{HELP_EXEC}" - )); - } - Ok(Invocation::Exec { - config: config.ok_or("error: exec: missing required --config ")?, - check, - verify_keys, - argv, - }) - } - Some("setup") => { - it.next(); - let mut config = None; - let mut recheck = false; - let mut unattended = false; - let mut force = false; - let mut keys_dir = None; - while let Some(a) = it.next() { - match a.as_str() { - "--config" => { - config = Some(PathBuf::from( - it.next().ok_or("error: --config requires a path")?, - )); - } - "--recheck" => recheck = true, - "--unattended" | "--non-interactive" => unattended = true, - "--force" => force = true, - "--keys-dir" => { - keys_dir = Some(PathBuf::from( - it.next().ok_or("error: --keys-dir requires a path")?, - )); - } - "--help" | "-h" => return Ok(Invocation::Help(Some("setup".into()))), - other => { - return Err(format!( - "error: setup: unknown option `{other}`\n\n{HELP_SETUP}" - )); - } - } - } - let config = config.ok_or("error: setup: missing required --config ")?; - Ok(Invocation::Setup { - config, - recheck, - unattended, - force, - keys_dir, - }) - } - Some("cleanup") => { - it.next(); - let mut config = None; - while let Some(a) = it.next() { - match a.as_str() { - "--config" => { - config = Some(PathBuf::from( - it.next().ok_or("error: --config requires a path")?, - )); - } - "--help" | "-h" => return Ok(Invocation::Help(Some("cleanup".into()))), - other => { - return Err(format!( - "error: cleanup: unknown option `{other}`\n\n{HELP_CLEANUP}" - )); - } - } - } - Ok(Invocation::Cleanup { - config: config.ok_or("error: cleanup: missing required --config ")?, - }) - } - // Serve mode (default, no subcommand keyword) - Some("--config") | Some("--bind") | Some("--allow-nonroot") => { - let mut config = None; - let mut bind = false; - let mut allow_nonroot = false; - while let Some(a) = it.next() { - match a.as_str() { - "--config" => { - config = Some(PathBuf::from( - it.next().ok_or("error: --config requires a path")?, - )); - } - "--bind" => bind = true, - "--allow-nonroot" => allow_nonroot = true, - "--help" | "-h" => return Ok(Invocation::Help(None)), - other => { - return Err(format!("error: unknown option `{other}`\n\n{HELP_TOP}")); - } - } - } - Ok(Invocation::Serve(Args { - config: config.ok_or("error: missing required --config ")?, - bind, - allow_nonroot, - })) - } - Some(other) => Err(format!( - "error: unknown subcommand `{other}`\n\nTry `postmaster help` for usage.\n" - )), - None => unreachable!("empty args handled above"), - } -} - -/// Launcher configuration for `postmaster exec` — THE cross-binding -/// contract. Generated by the Nix module (later: other bindings); contains -/// only public data: store paths of ciphertext, key *names*, socket paths. -#[derive(Deserialize, Debug)] -#[serde(deny_unknown_fields)] -pub struct ExecConfig { - pub mode: ExecMode, - /// Ordered key sources; see launcher::load_ring for selection rules. - #[serde(default)] - pub keys: Vec, - /// Encrypted env files, in precedence order (first wins unless overload). - #[serde(default)] - pub env_files: Vec, - /// Encrypted `postmaster_bundle` files, in precedence order. - /// Each file is a JSON container with `format: "postmaster.bundle"`. - /// Entries are merged with `env_files` entries; bundle keys use the - /// same identifier rule and the same injection modes. - #[serde(default)] - pub bundle_files: Vec, - /// Any undecryptable value aborts before exec (fail closed). - #[serde(default = "default_true")] - pub strict: bool, - /// File values override process env; later files override earlier. - #[serde(default)] - pub overload: bool, - /// files/credentials(darwin) mode: where plaintext files land. - #[serde(default)] - pub secrets_dir: Option, - /// files mode: keys ALSO exported as real env vars. - #[serde(default)] - pub passthrough: Vec, - /// credentials mode: keys exposed as $CREDENTIALS_DIRECTORY/. - #[serde(default)] - pub credential_keys: Vec, - /// credentials mode, darwin: key → postmaster socket to fetch from. - /// Non-empty selects the fetch path; empty means systemd already - /// materialized the credentials. - #[serde(default)] - pub sockets: HashMap, - /// darwin: refuse to write plaintext unless this mount point is the - /// HFS ramdisk and secrets_dir is a directory we own. - #[serde(default)] - pub verify_ramdisk: Option, -} - -#[derive(Deserialize, Debug, Clone, Copy, PartialEq, Eq)] -#[serde(rename_all = "snake_case")] -pub enum ExecMode { - Env, - Files, - Credentials, -} - -/// Where the launcher's private keys come from. Selection contract: -/// `credential` is skippable (absent $CREDENTIALS_DIRECTORY or file ⇒ try -/// the next source); `file`/`keychain`/`environment` are terminal — once -/// reached, their failure is the launcher's failure (fail closed). -#[derive(Deserialize, Debug, Clone)] -#[serde(rename_all = "snake_case")] -pub enum KeySourceSpec { - Credential(String), - File(PathBuf), - Keychain(String), - Environment, -} - -impl ExecConfig { - /// Validate the public shape of an exec config without touching local - /// secret material, decrypting values, probing sockets, or inspecting the - /// host filesystem. This is the parser-authoritative `--check` contract - /// automation bindings can run in CI before deployment. - pub fn validate_shape(&self) -> Result<(), String> { - validate_key_sources(&self.keys)?; - validate_ident_list("passthrough", &self.passthrough)?; - validate_mode_irrelevant_fields(self)?; - validate_mode_required_fields(self)?; - Ok(()) - } -} - -fn validate_mode_required_fields(cfg: &ExecConfig) -> Result<(), String> { - match cfg.mode { - ExecMode::Env => { - validate_decrypting_mode(cfg, "env")?; - } - ExecMode::Files => { - validate_decrypting_mode(cfg, "files")?; - if cfg.secrets_dir.is_none() { - return Err("files mode requires secrets_dir".into()); - } - } - ExecMode::Credentials => { - if cfg.credential_keys.is_empty() { - return Err("credentials mode requires credential_keys".into()); - } - validate_ident_list("credential_keys", &cfg.credential_keys)?; - if !cfg.sockets.is_empty() { - if cfg.secrets_dir.is_none() { - return Err("credentials(fetch) mode requires secrets_dir".into()); - } - for key in &cfg.credential_keys { - if !cfg.sockets.contains_key(key) { - return Err(format!("{key}: no socket mapped in exec config")); - } - } - } - } - } - Ok(()) -} - -/// Reject fields that are irrelevant to the selected mode. This catches -/// binding bugs early — before any secret material transits — so a config -/// generator that accidentally includes `env_files` in a credentials-mode -/// config or `credential_keys` in an env-mode config fails at `--check` -/// rather than silently ignoring the stray field. Default/empty values -/// (empty vecs, `None`, `false`) are accepted since serde fills them in -/// even when the generator omits the field entirely. -fn validate_mode_irrelevant_fields(cfg: &ExecConfig) -> Result<(), String> { - match cfg.mode { - ExecMode::Env => { - if cfg.secrets_dir.is_some() { - return Err("env mode does not use secrets_dir".into()); - } - if !cfg.credential_keys.is_empty() { - return Err("env mode does not use credential_keys".into()); - } - if !cfg.sockets.is_empty() { - return Err("env mode does not use sockets".into()); - } - if cfg.verify_ramdisk.is_some() { - return Err("env mode does not use verify_ramdisk".into()); - } - if !cfg.passthrough.is_empty() { - return Err("env mode does not use passthrough".into()); - } - } - ExecMode::Files => { - if !cfg.credential_keys.is_empty() { - return Err("files mode does not use credential_keys".into()); - } - if !cfg.sockets.is_empty() { - return Err("files mode does not use sockets".into()); - } - } - ExecMode::Credentials => { - if !cfg.keys.is_empty() { - return Err( - "credentials mode does not use keys (key material lives on the daemon)".into(), - ); - } - if !cfg.env_files.is_empty() { - return Err( - "credentials mode does not use env_files (ciphertext lives on the daemon)" - .into(), - ); - } - if !cfg.bundle_files.is_empty() { - return Err( - "credentials mode does not use bundle_files (ciphertext lives on the daemon)" - .into(), - ); - } - if cfg.overload { - return Err("credentials mode does not use overload".into()); - } - if !cfg.passthrough.is_empty() { - return Err("credentials mode does not use passthrough".into()); - } - } - } - Ok(()) -} - -fn validate_decrypting_mode(cfg: &ExecConfig, mode: &str) -> Result<(), String> { - if cfg.env_files.is_empty() && cfg.bundle_files.is_empty() { - return Err(format!( - "{mode} mode requires env_files or bundle_files (at least one non-empty)" - )); - } - if cfg.keys.is_empty() { - return Err(format!("{mode} mode requires keys")); - } - for path in &cfg.env_files { - KeyNaming::Env.key_var_for(path)?; - } - Ok(()) -} - -fn validate_key_sources(specs: &[KeySourceSpec]) -> Result<(), String> { - for spec in specs { - match spec { - KeySourceSpec::Credential(name) => validate_credential_source_name(name)?, - KeySourceSpec::File(path) if path.starts_with("/nix/store") => { - return Err(format!( - "{}: refusing plaintext private keys from the world-readable Nix store", - path.display() - )); - } - _ => {} - } - } - Ok(()) -} - -fn validate_credential_source_name(name: &str) -> Result<(), String> { - if name.contains('\0') { - return Err(format!( - "credential source {name:?}: contains NUL byte (not a valid path component)" - )); - } - let mut components = Path::new(name).components(); - match (components.next(), components.next()) { - (Some(Component::Normal(_)), None) => Ok(()), - _ => Err(format!( - "credential source {name:?}: must be a single relative path component" - )), - } -} - -fn validate_ident_list(field: &str, keys: &[String]) -> Result<(), String> { - for key in keys { - if !crate::keys::is_ident(key) { - return Err(format!("{field} entry {key:?}: not a valid identifier")); - } - } - Ok(()) -} - -fn default_true() -> bool { - true -} - -#[cfg(test)] -#[allow(unused_qualifications, clippy::panic, clippy::unwrap_used)] -mod tests { - use super::*; - - fn parse(v: &[&str]) -> Result { - parse_args_from(v.iter().map(ToString::to_string)) - } - - #[test] - fn parse_exec() { - match parse(&[ - "exec", "--config", "/e.json", "--", "/bin/app", "--flag", "x", - ]) { - Ok(Invocation::Exec { - config, - check, - verify_keys, - argv, - }) => { - assert_eq!(config, PathBuf::from("/e.json")); - assert!(!check); - assert!(!verify_keys); - assert_eq!(argv, vec!["/bin/app", "--flag", "x"]); - } - other => panic!("expected Exec, got {other:?}"), - } - } - - #[test] - fn parse_exec_check() { - match parse(&["exec", "--config", "/e.json", "--check"]) { - Ok(Invocation::Exec { - config, - check, - argv, - .. - }) => { - assert_eq!(config, PathBuf::from("/e.json")); - assert!(check); - assert!(argv.is_empty()); - } - other => panic!("expected Exec check, got {other:?}"), - } - } - - #[test] - fn parse_exec_verify_keys() { - match parse(&[ - "exec", - "--config", - "/e.json", - "--verify-keys", - "--", - "/bin/app", - ]) { - Ok(Invocation::Exec { - config, - check, - verify_keys, - argv, - }) => { - assert_eq!(config, PathBuf::from("/e.json")); - assert!(!check); - assert!(verify_keys); - assert_eq!(argv, vec!["/bin/app"]); - } - other => panic!("expected Exec with --verify-keys, got {other:?}"), - } - } - - #[test] - fn parse_exec_requires_command() { - assert!(parse(&["exec", "--config", "/e.json"]).is_err()); - assert!(parse(&["exec", "--config", "/e.json", "--"]).is_err()); - assert!(parse(&["exec", "--config", "/e.json", "--check", "--", "/bin/app"]).is_err()); - } - - #[test] - fn parse_fetch_and_serve_still_work() { - assert!(matches!( - parse(&["fetch", "/s.sock"]), - Ok(Invocation::Fetch(_)) - )); - assert!(matches!( - parse(&["--config", "/c.json", "--bind"]), - Ok(Invocation::Serve(Args { bind: true, .. })) - )); - } - - #[test] - fn parse_help_top_level() { - assert!(matches!(parse(&["--help"]), Ok(Invocation::Help(None)))); - assert!(matches!(parse(&["-h"]), Ok(Invocation::Help(None)))); - } - - #[test] - fn parse_help_subcommand() { - assert!(matches!(parse(&["help"]), Ok(Invocation::Help(None)))); - assert!(matches!( - parse(&["help", "exec"]), - Ok(Invocation::Help(Some(s))) if s == "exec" - )); - assert!(matches!( - parse(&["help", "setup"]), - Ok(Invocation::Help(Some(s))) if s == "setup" - )); - } - - #[test] - fn parse_version() { - assert!(matches!(parse(&["--version"]), Ok(Invocation::Version))); - assert!(matches!(parse(&["-V"]), Ok(Invocation::Version))); - } - - #[test] - fn parse_no_args_fails() { - assert!(parse(&[]).is_err()); - } - - #[test] - fn parse_unknown_subcommand_fails() { - let err = parse(&["bogus"]).unwrap_err(); - assert!(err.contains("unknown subcommand"), "{err}"); - assert!(err.contains("Try `postmaster help`"), "{err}"); - } - - #[test] - fn parse_help_in_exec_subcommand() { - assert!(matches!( - parse(&["exec", "--help"]), - Ok(Invocation::Help(Some(s))) if s == "exec" - )); - } - - #[test] - fn parse_help_in_setup_subcommand() { - assert!(matches!( - parse(&["setup", "--help"]), - Ok(Invocation::Help(Some(s))) if s == "setup" - )); - } - - #[test] - fn parse_setup_flags() { - assert!(matches!( - parse(&["setup", "--config", "/e.json", "--recheck"]), - Ok(Invocation::Setup { recheck: true, .. }) - )); - assert!(matches!( - parse(&["setup", "--config", "/e.json", "--unattended"]), - Ok(Invocation::Setup { - unattended: true, - .. - }) - )); - assert!(matches!( - parse(&["setup", "--config", "/e.json", "--force"]), - Ok(Invocation::Setup { force: true, .. }) - )); - assert!(matches!( - parse(&["setup", "--config", "/e.json", "--keys-dir", "/custom"]), - Ok(Invocation::Setup { keys_dir: Some(p), .. }) if &*p == std::path::Path::new("/custom") - )); - } - - #[test] - fn parse_cleanup() { - assert!(matches!( - parse(&["cleanup", "--config", "/e.json"]), - Ok(Invocation::Cleanup { config }) if &*config == std::path::Path::new("/e.json") - )); - assert!(parse(&["cleanup"]).is_err()); - assert!(parse(&["cleanup", "--config"]).is_err()); - } - - #[test] - fn parse_help_in_cleanup_subcommand() { - assert!(matches!( - parse(&["cleanup", "--help"]), - Ok(Invocation::Help(Some(s))) if s == "cleanup" - )); - } - - #[test] - fn key_var_for_edge_cases() { - assert!( - KeyNaming::Env - .key_var_for(std::path::Path::new("no-dot-env")) - .is_err() - ); - } - - #[test] - fn exec_config_parses() { - let json = r#"{ - "mode": "files", - "keys": [{"credential": "postmaster-myapp"}, "environment"], - "env_files": ["/nix/store/x/.env.production"], - "strict": true, - "overload": false, - "secrets_dir": "/run/postmaster", - "passthrough": ["RUST_LOG"] - }"#; - let c: ExecConfig = serde_json::from_str(json).unwrap(); - assert!(matches!(c.mode, ExecMode::Files)); - assert_eq!(c.keys.len(), 2); - assert!(matches!(c.keys[1], KeySourceSpec::Environment)); - assert!(c.strict && !c.overload); - assert!(c.sockets.is_empty() && c.verify_ramdisk.is_none()); - } - - #[test] - fn exec_config_minimal_credentials() { - let json = r#"{"mode":"credentials","credential_keys":["DB_URL"]}"#; - let c: ExecConfig = serde_json::from_str(json).unwrap(); - assert!(matches!(c.mode, ExecMode::Credentials)); - assert!(c.strict, "strict must default to true"); - assert_eq!(c.credential_keys, vec!["DB_URL"]); - c.validate_shape().unwrap(); - } - - #[test] - fn exec_config_rejects_unknown_fields() { - let json = r#"{"mode":"credentials","credential_keys":["DB_URL"],"adapter":"dotenvx"}"#; - let err = serde_json::from_str::(json).unwrap_err(); - assert!( - err.to_string().contains("unknown field"), - "unexpected error: {err}" - ); - } - - #[test] - fn exec_config_validate_shape_catches_mode_requirements() { - let files_missing_dir: ExecConfig = serde_json::from_str( - r#"{"mode":"files","keys":["environment"],"env_files":["/nix/store/x/.env"]}"#, - ) - .unwrap(); - assert!( - files_missing_dir - .validate_shape() - .unwrap_err() - .contains("secrets_dir") - ); - - let invalid_credential_key: ExecConfig = - serde_json::from_str(r#"{"mode":"credentials","credential_keys":["../DB_URL"]}"#) - .unwrap(); - assert!( - invalid_credential_key - .validate_shape() - .unwrap_err() - .contains("identifier") - ); - - let store_key: ExecConfig = serde_json::from_str( - r#"{"mode":"env","keys":[{"file":"/nix/store/abc/.env.keys"}],"env_files":["/nix/store/x/.env"]}"#, - ) - .unwrap(); - assert!( - store_key - .validate_shape() - .unwrap_err() - .contains("Nix store") - ); - } - - #[test] - fn validate_shape_rejects_mode_irrelevant_fields() { - // env mode should reject secrets_dir, credential_keys, sockets, - // verify_ramdisk, and passthrough. - let env_with_secrets_dir: ExecConfig = serde_json::from_str( - r#"{"mode":"env","keys":["environment"],"env_files":["/nix/store/x/.env"],"secrets_dir":"/run/x"}"#, - ) - .unwrap(); - assert!( - env_with_secrets_dir - .validate_shape() - .unwrap_err() - .contains("env mode does not use secrets_dir") - ); - - let env_with_credential_keys: ExecConfig = serde_json::from_str( - r#"{"mode":"env","keys":["environment"],"env_files":["/nix/store/x/.env"],"credential_keys":["DB"]}"#, - ) - .unwrap(); - assert!( - env_with_credential_keys - .validate_shape() - .unwrap_err() - .contains("env mode does not use credential_keys") - ); - - // files mode should reject credential_keys and sockets. - let files_with_sockets: ExecConfig = serde_json::from_str( - r#"{"mode":"files","keys":["environment"],"env_files":["/nix/store/x/.env"],"secrets_dir":"/run/x","sockets":{"DB":"/s.sock"}}"#, - ) - .unwrap(); - assert!( - files_with_sockets - .validate_shape() - .unwrap_err() - .contains("files mode does not use sockets") - ); - - // credentials mode should reject keys, env_files, overload, passthrough. - let creds_with_env_files: ExecConfig = serde_json::from_str( - r#"{"mode":"credentials","credential_keys":["DB"],"env_files":["/nix/store/x/.env"]}"#, - ) - .unwrap(); - assert!( - creds_with_env_files - .validate_shape() - .unwrap_err() - .contains("credentials mode does not use env_files") - ); - - let creds_with_overload: ExecConfig = serde_json::from_str( - r#"{"mode":"credentials","credential_keys":["DB"],"overload":true}"#, - ) - .unwrap(); - assert!( - creds_with_overload - .validate_shape() - .unwrap_err() - .contains("credentials mode does not use overload") - ); - } -} diff --git a/src/exec_config.rs b/src/exec_config.rs new file mode 100644 index 0000000..49e2c93 --- /dev/null +++ b/src/exec_config.rs @@ -0,0 +1,413 @@ +//! Exec configuration — the `exec.json` data model and validation. +//! +//! This module defines the cross-binding contract for `postmaster exec`: +//! the `ExecConfig` struct, `ExecMode` enum, `KeySourceSpec` enum, and +//! all validation functions that check config shape without touching +//! local secret material or the host filesystem. + +use std::collections::HashMap; +use std::path::{Component, Path, PathBuf}; + +use serde::Deserialize; + +use crate::adapter::KeyNaming; + +/// Public launcher configuration shared by deployment integrations. +/// Contains input paths, key-source names, and projection settings, not secret values. +#[derive(Deserialize, Debug)] +#[serde(deny_unknown_fields)] +pub struct ExecConfig { + /// How resolved values are projected into the child process. + pub mode: ExecMode, + /// Ordered key sources; see launcher::load_ring for selection rules. + #[serde(default)] + pub keys: Vec, + /// Encrypted env files, in precedence order (first wins unless overload). + #[serde(default)] + pub env_files: Vec, + /// Encrypted `postmaster_bundle` files, resolved after `env_files`. + /// Each file is a JSON container with `format: "postmaster.bundle"`. + /// The first definition wins unless `overload` selects the last. + /// Bundle keys use the same identifier rule and injection modes. + #[serde(default)] + pub bundle_files: Vec, + /// Undecryptable dotenv values abort before exec unless false. + /// Bundle authentication failures always abort. + #[serde(default = "default_true")] + pub strict: bool, + /// File values override process env; later files override earlier. + #[serde(default)] + pub overload: bool, + /// Output directory for files mode and the credentials socket-fetch path. + #[serde(default)] + pub secrets_dir: Option, + /// Files-mode keys also exported as environment values alongside file pointers. + #[serde(default)] + pub passthrough: Vec, + /// credentials mode: keys exposed as `$CREDENTIALS_DIRECTORY/`. + #[serde(default)] + pub credential_keys: Vec, + /// Credentials-mode key names mapped to local Postmaster sockets. + /// Non-empty selects the fetch path; empty means systemd already + /// materialized the credentials. + #[serde(default)] + pub sockets: HashMap, + /// On macOS, require a RAM-backed HFS mount and an owned `secrets_dir` + /// on that device before writing plaintext. + #[serde(default)] + pub verify_ramdisk: Option, +} + +/// How resolved secret values are projected into the child process. +#[derive(Deserialize, Debug, Clone, Copy, PartialEq, Eq)] +#[serde(rename_all = "snake_case")] +pub enum ExecMode { + /// Export all resolved values as environment variables. + Env, + /// Write each resolved value as a file under `secrets_dir`. + Files, + /// systemd credentials: export `_FILE` pointers into + /// `$CREDENTIALS_DIRECTORY`. + Credentials, +} + +/// Where the launcher's private keys come from. Selection contract: +/// `credential` is skippable (absent $CREDENTIALS_DIRECTORY or file ⇒ try +/// the next source); `file`/`keychain`/`environment` are terminal — once +/// reached, their failure is the launcher's failure (fail closed). +#[derive(Deserialize, Debug, Clone)] +#[serde(rename_all = "snake_case")] +pub enum KeySourceSpec { + /// Read from `$CREDENTIALS_DIRECTORY/` (systemd LoadCredential). + Credential(String), + /// Read from a local file path (must not be in the Nix store). + File(PathBuf), + /// Read from macOS Keychain (terminal, macOS only). + Keychain(String), + /// Read the required adapters' private-key variables from the environment. + Environment, +} + +impl ExecConfig { + /// Validate the public shape of an exec config without touching local + /// secret material, decrypting values, probing sockets, or inspecting the + /// host filesystem. This is the parser-authoritative `--check` contract + /// automation bindings can run in CI before deployment. + pub fn validate_shape(&self) -> Result<(), String> { + validate_key_sources(&self.keys)?; + validate_ident_list("passthrough", &self.passthrough)?; + validate_mode_irrelevant_fields(self)?; + validate_mode_required_fields(self)?; + Ok(()) + } + + /// Return the key-naming conventions required by the configured inputs. + /// `load_ring` admits only these namespaces: `Env` for dotenv files, + /// `Bundle` for bundles, or both for mixed inputs. + pub fn required_namings(&self) -> Vec { + let mut namings = Vec::with_capacity(2); + if !self.env_files.is_empty() { + namings.push(KeyNaming::Env); + } + if !self.bundle_files.is_empty() { + namings.push(KeyNaming::Bundle); + } + namings + } +} + +fn validate_mode_required_fields(cfg: &ExecConfig) -> Result<(), String> { + match cfg.mode { + ExecMode::Env => { + validate_decrypting_mode(cfg, "env")?; + } + ExecMode::Files => { + validate_decrypting_mode(cfg, "files")?; + if cfg.secrets_dir.is_none() { + return Err("files mode requires secrets_dir".into()); + } + } + ExecMode::Credentials => { + if cfg.credential_keys.is_empty() { + return Err("credentials mode requires credential_keys".into()); + } + validate_ident_list("credential_keys", &cfg.credential_keys)?; + if !cfg.sockets.is_empty() { + if cfg.secrets_dir.is_none() { + return Err("credentials(fetch) mode requires secrets_dir".into()); + } + for key in &cfg.credential_keys { + if !cfg.sockets.contains_key(key) { + return Err(format!("{key}: no socket mapped in exec config")); + } + } + } + } + } + Ok(()) +} + +/// Reject fields that are irrelevant to the selected mode. This catches +/// binding bugs early — before any secret material transits — so a config +/// generator that accidentally includes `env_files` in a credentials-mode +/// config or `credential_keys` in an env-mode config fails at `--check` +/// rather than silently ignoring the stray field. Default/empty values +/// (empty vecs, `None`, `false`) are accepted since serde fills them in +/// even when the generator omits the field entirely. +fn validate_mode_irrelevant_fields(cfg: &ExecConfig) -> Result<(), String> { + match cfg.mode { + ExecMode::Env => { + if cfg.secrets_dir.is_some() { + return Err("env mode does not use secrets_dir".into()); + } + if !cfg.credential_keys.is_empty() { + return Err("env mode does not use credential_keys".into()); + } + if !cfg.sockets.is_empty() { + return Err("env mode does not use sockets".into()); + } + if cfg.verify_ramdisk.is_some() { + return Err("env mode does not use verify_ramdisk".into()); + } + if !cfg.passthrough.is_empty() { + return Err("env mode does not use passthrough".into()); + } + } + ExecMode::Files => { + if !cfg.credential_keys.is_empty() { + return Err("files mode does not use credential_keys".into()); + } + if !cfg.sockets.is_empty() { + return Err("files mode does not use sockets".into()); + } + } + ExecMode::Credentials => { + if !cfg.keys.is_empty() { + return Err( + "credentials mode does not use keys (key material lives on the daemon)".into(), + ); + } + if !cfg.env_files.is_empty() { + return Err( + "credentials mode does not use env_files (ciphertext lives on the daemon)" + .into(), + ); + } + if !cfg.bundle_files.is_empty() { + return Err( + "credentials mode does not use bundle_files (ciphertext lives on the daemon)" + .into(), + ); + } + if cfg.overload { + return Err("credentials mode does not use overload".into()); + } + if !cfg.passthrough.is_empty() { + return Err("credentials mode does not use passthrough".into()); + } + } + } + Ok(()) +} + +fn validate_decrypting_mode(cfg: &ExecConfig, mode: &str) -> Result<(), String> { + if cfg.env_files.is_empty() && cfg.bundle_files.is_empty() { + return Err(format!( + "{mode} mode requires env_files or bundle_files (at least one non-empty)" + )); + } + if cfg.keys.is_empty() { + return Err(format!("{mode} mode requires keys")); + } + for path in &cfg.env_files { + KeyNaming::Env.key_var_for(path)?; + } + Ok(()) +} + +fn validate_key_sources(specs: &[KeySourceSpec]) -> Result<(), String> { + for spec in specs { + match spec { + KeySourceSpec::Credential(name) => validate_credential_source_name(name)?, + KeySourceSpec::File(path) if path.starts_with("/nix/store") => { + return Err(format!( + "{}: refusing plaintext private keys from the world-readable Nix store", + path.display() + )); + } + _ => {} + } + } + Ok(()) +} + +pub(crate) fn validate_credential_source_name(name: &str) -> Result<(), String> { + if name.contains('\0') { + return Err(format!( + "credential source {name:?}: contains NUL byte (not a valid path component)" + )); + } + let mut components = Path::new(name).components(); + match (components.next(), components.next()) { + (Some(Component::Normal(_)), None) => Ok(()), + _ => Err(format!( + "credential source {name:?}: must be a single relative path component" + )), + } +} + +fn validate_ident_list(field: &str, keys: &[String]) -> Result<(), String> { + for key in keys { + if !crate::keys::is_ident(key) { + return Err(format!("{field} entry {key:?}: not a valid identifier")); + } + } + Ok(()) +} + +fn default_true() -> bool { + true +} + +#[cfg(test)] +#[allow(unused_qualifications, clippy::panic, clippy::unwrap_used)] +/// Tests for exec config parsing and validation. +mod tests { + use super::*; + + #[test] + fn exec_config_parses() { + let json = r#"{ + "mode": "files", + "keys": [{"credential": "postmaster-myapp"}, "environment"], + "env_files": ["/nix/store/x/.env.production"], + "strict": true, + "overload": false, + "secrets_dir": "/run/postmaster", + "passthrough": ["RUST_LOG"] + }"#; + let c: ExecConfig = serde_json::from_str(json).unwrap(); + assert!(matches!(c.mode, ExecMode::Files)); + assert_eq!(c.keys.len(), 2); + assert!(matches!(c.keys[1], KeySourceSpec::Environment)); + assert!(c.strict && !c.overload); + assert!(c.sockets.is_empty() && c.verify_ramdisk.is_none()); + } + + #[test] + fn exec_config_minimal_credentials() { + let json = r#"{"mode":"credentials","credential_keys":["DB_URL"]}"#; + let c: ExecConfig = serde_json::from_str(json).unwrap(); + assert!(matches!(c.mode, ExecMode::Credentials)); + assert!(c.strict, "strict must default to true"); + + c.validate_shape().unwrap(); + } + + #[test] + fn exec_config_rejects_unknown_fields() { + let json = r#"{"mode":"credentials","credential_keys":["DB_URL"],"adapter":"dotenvx"}"#; + let err = serde_json::from_str::(json).unwrap_err(); + assert!( + err.to_string().contains("unknown field"), + "unexpected error: {err}" + ); + } + + #[test] + fn exec_config_validate_shape_catches_mode_requirements() { + let files_missing_dir: ExecConfig = serde_json::from_str( + r#"{"mode":"files","keys":["environment"],"env_files":["/nix/store/x/.env"]}"#, + ) + .unwrap(); + assert!( + files_missing_dir + .validate_shape() + .unwrap_err() + .contains("secrets_dir") + ); + + let invalid_credential_key: ExecConfig = + serde_json::from_str(r#"{"mode":"credentials","credential_keys":["../DB_URL"]}"#) + .unwrap(); + assert!( + invalid_credential_key + .validate_shape() + .unwrap_err() + .contains("identifier") + ); + + let store_key: ExecConfig = serde_json::from_str( + r#"{"mode":"env","keys":[{"file":"/nix/store/abc/.env.keys"}],"env_files":["/nix/store/x/.env"]}"#, + ) + .unwrap(); + assert!( + store_key + .validate_shape() + .unwrap_err() + .contains("Nix store") + ); + } + + #[test] + fn validate_shape_rejects_mode_irrelevant_fields() { + // env mode should reject secrets_dir, credential_keys, sockets, + // verify_ramdisk, and passthrough. + let env_with_secrets_dir: ExecConfig = serde_json::from_str( + r#"{"mode":"env","keys":["environment"],"env_files":["/nix/store/x/.env"],"secrets_dir":"/run/x"}"#, + ) + .unwrap(); + assert!( + env_with_secrets_dir + .validate_shape() + .unwrap_err() + .contains("env mode does not use secrets_dir") + ); + + let env_with_credential_keys: ExecConfig = serde_json::from_str( + r#"{"mode":"env","keys":["environment"],"env_files":["/nix/store/x/.env"],"credential_keys":["DB"]}"#, + ) + .unwrap(); + assert!( + env_with_credential_keys + .validate_shape() + .unwrap_err() + .contains("env mode does not use credential_keys") + ); + + // files mode should reject credential_keys and sockets. + let files_with_sockets: ExecConfig = serde_json::from_str( + r#"{"mode":"files","keys":["environment"],"env_files":["/nix/store/x/.env"],"secrets_dir":"/run/x","sockets":{"DB":"/s.sock"}}"#, + ) + .unwrap(); + assert!( + files_with_sockets + .validate_shape() + .unwrap_err() + .contains("files mode does not use sockets") + ); + + // credentials mode should reject keys, env_files, overload, passthrough. + let creds_with_env_files: ExecConfig = serde_json::from_str( + r#"{"mode":"credentials","credential_keys":["DB"],"env_files":["/nix/store/x/.env"]}"#, + ) + .unwrap(); + assert!( + creds_with_env_files + .validate_shape() + .unwrap_err() + .contains("credentials mode does not use env_files") + ); + + let creds_with_overload: ExecConfig = serde_json::from_str( + r#"{"mode":"credentials","credential_keys":["DB"],"overload":true}"#, + ) + .unwrap(); + assert!( + creds_with_overload + .validate_shape() + .unwrap_err() + .contains("credentials mode does not use overload") + ); + } +} diff --git a/src/keys.rs b/src/keys.rs deleted file mode 100644 index 9fe9343..0000000 --- a/src/keys.rs +++ /dev/null @@ -1,817 +0,0 @@ -//! Key loading, variable name resolution, and ciphertext decryption. -//! -//! All secret material is Zeroized. Decryption is tried with rotation candidates. -//! Plaintext values (from `dotenvx set --plain`) are passed through. -//! -//! Key-naming conventions are abstracted via the `KeyNaming` trait -//! (see `adapter.rs`), so the core logic is adapter-neutral. The `.env` -//! adapter's `KeyNaming::Env` is the first implementation. - -#![allow(missing_docs, missing_debug_implementations)] - -use std::collections::HashMap; -use std::path::{Path, PathBuf}; - -use base64::Engine; -use base64::engine::general_purpose::STANDARD as BASE64; -use zeroize::{Zeroize, Zeroizing}; - -use crate::adapter::KeyNaming; -use crate::config::Entry; - -/// Full variable name (adapter-specific, e.g. DOTENV_PRIVATE_KEY[_]) -/// → candidate secret keys. Multiple candidates per name come from -/// comma-separated rotation convention; decryption tries each in order. -#[derive(Debug)] -pub struct KeyRing(HashMap>>); - -impl KeyRing { - /// Look up candidate keys for a given key variable name. - /// Returns `None` if the variable has no candidates in the ring. - pub fn candidates(&self, var: &str) -> Option<&[Zeroizing<[u8; 32]>]> { - self.0.get(var).map(|v| v.as_slice()) - } - /// Load a `.env.keys` file from `path` and build a key ring. - /// - /// Security invariants enforced on the opened file (all checked on the - /// file descriptor, never the path, to eliminate TOCTOU windows): - /// - `O_NOFOLLOW`: reject a symlink at `path` (defense-in-depth; also - /// closes the credential-source symlink leg of audit finding #2). - /// - `mode & 0o077 == 0`: no group or world read/write/exec. A keys - /// file accidentally `chmod 0644` would expose private keys to every - /// process on the host; fail closed instead. - /// - `st_uid == euid`: the file must be owned by the service user. - pub fn load(path: &Path, naming: KeyNaming) -> Result { - let oflags = - rustix::fs::OFlags::RDONLY | rustix::fs::OFlags::NOFOLLOW | rustix::fs::OFlags::CLOEXEC; - let fd = rustix::fs::open(path, oflags, rustix::fs::Mode::empty()).map_err(|e| { - format!( - "keys file {}: {e} (refusing to follow a symlink)", - path.display() - ) - })?; - let stat = rustix::fs::fstat(&fd) - .map_err(|e| format!("keys file {}: fstat: {e}", path.display()))?; - let mode = rustix::fs::Mode::from_bits_truncate(stat.st_mode); - // Reject group or world accessibility. 0o077 masks both RWXG and RWXO. - if mode.intersects(rustix::fs::Mode::RWXG | rustix::fs::Mode::RWXO) { - return Err(format!( - "keys file {}: permissions {:#o} are group/world accessible; expected 0400 or 0600 (fail closed)", - path.display(), - stat.st_mode - )); - } - let euid = rustix::process::geteuid().as_raw(); - if stat.st_uid != euid { - return Err(format!( - "keys file {}: owned by uid {} but postmaster euid is {euid} (fail closed)", - path.display(), - stat.st_uid - )); - } - let file = std::fs::File::from(fd); - let iter = dotenvy::from_read_iter(file); - let mut pairs = Vec::new(); - for item in iter { - let (k, v) = item.map_err(|e| format!("keys file {}: {e}", path.display()))?; - pairs.push((k, Zeroizing::new(v))); - } - Self::from_pairs(pairs, naming).map_err(|e| format!("keys file {}: {e}", path.display())) - } - - /// Core parser shared by every key source: keep keys matching the - /// adapter's key prefix, split comma-separated rotation candidates, - /// hex-decode to 32-byte zeroized keys. Empty result is an error - /// (fail closed). Takes `Zeroizing` values so callers never - /// hand key material as a plain heap String that drops without - /// zeroization. - pub fn from_pairs( - pairs: impl IntoIterator)>, - naming: KeyNaming, - ) -> Result { - let prefix = naming.key_prefix(); - let mut map: HashMap>> = HashMap::new(); - for (name, mut value) in pairs { - if !name.starts_with(prefix) { - value.zeroize(); - continue; - } - let mut keys = Vec::new(); - for part in value.split(',') { - let part = part.trim(); - if part.is_empty() { - continue; - } - let mut raw = - hex::decode(part).map_err(|_| format!("{name}: entry is not valid hex"))?; - if raw.len() != 32 { - raw.zeroize(); - return Err(format!("{name}: expected a 32-byte key")); - } - let mut arr = [0_u8; 32]; - arr.copy_from_slice(&raw); - raw.zeroize(); - keys.push(Zeroizing::new(arr)); - } - value.zeroize(); - if keys.is_empty() { - return Err(format!("{name}: no usable keys")); - } - map.insert(name, keys); - } - if map.is_empty() { - return Err(naming.empty_error()); - } - Ok(KeyRing(map)) - } - - /// Private key variables from the process environment (external - /// provisioning; `key.file = null` in the module). Reads all - /// variables matching the adapter's key prefix. - pub fn from_env(naming: KeyNaming) -> Result { - let prefix = naming.key_prefix(); - Self::from_pairs( - std::env::vars() - .filter(|(k, _)| k.starts_with(prefix)) - .map(|(k, v)| (k, Zeroizing::new(v))), - naming, - ) - .map_err(|e| format!("environment: {e}")) - } - - /// macOS System keychain: one generic-password item per variable, - /// service = `service`, account = the adapter's key variable name. - /// Only the vars actually needed (derived from artifact names) are - /// fetched. - #[cfg(target_os = "macos")] - pub fn from_keychain( - service: &str, - vars: &[String], - naming: KeyNaming, - ) -> Result { - // Audit finding #3: verify the integrity of /usr/bin/security - // before invoking it. On macOS the binary is SIP-protected, but - // verify the code signature at runtime as defense-in-depth rather - // than trusting the path implicitly. - verify_external_binary(Path::new("/usr/bin/security"))?; - let mut pairs = Vec::new(); - for var in vars { - let out = std::process::Command::new("/usr/bin/security") - .args(["find-generic-password", "-s", service, "-a", var, "-w"]) - .output() - .map_err(|e| format!("security: {e}"))?; - if !out.status.success() { - return Err(format!( - "keychain {service}: no item for account {var} (fail closed)" - )); - } - let mut val = Zeroizing::new( - String::from_utf8(out.stdout) - .map_err(|_| format!("keychain {service}/{var}: not UTF-8"))?, - ); - // Zeroizing the trimmed copy: the value is wrapped in Zeroizing - // before being passed to from_pairs, so key material is zeroized - // on drop at every stage. No plain-String window remains. - let trimmed = Zeroizing::new(val.trim().to_string()); - pairs.push((var.clone(), trimmed)); - val.zeroize(); - } - Self::from_pairs(pairs, naming).map_err(|e| format!("keychain {service}: {e}")) - } -} - -/// Verify the integrity of an external binary before invoking it as part -/// of a secret-handling path. This is a defense-in-depth trust boundary -/// check (audit finding #3): the binary path is a trust root, and we -/// verify it has not been tampered with before exec. -/// -/// On macOS: `codesign -v ` verifies the code signature. The binary -/// is additionally SIP-protected, so this catches a hypothetical SIP -/// bypass or a misconfigured environment. -/// -/// On Linux: verify the file is a regular file, owned by root (uid 0), -/// and not world-writable. There is no universal code-signing mechanism -/// on Linux, so ownership and permission checks are the practical -/// defense-in-depth boundary. -pub fn verify_external_binary(path: &Path) -> Result<(), String> { - #[cfg(target_os = "macos")] - { - let out = std::process::Command::new("/usr/bin/codesign") - .args(["-v", path.to_str().unwrap_or("")]) - .output() - .map_err(|e| format!("{}: codesign verification failed: {e}", path.display()))?; - if !out.status.success() { - return Err(format!( - "{}: code signature verification failed (audit finding #3 trust boundary)", - path.display() - )); - } - } - #[cfg(not(target_os = "macos"))] - { - use std::os::unix::fs::MetadataExt; - let md = std::fs::symlink_metadata(path) - .map_err(|e| format!("{}: cannot stat external binary: {e}", path.display()))?; - if md.file_type().is_symlink() { - return Err(format!( - "{}: external binary is a symlink; refusing to trust a symlinked binary", - path.display() - )); - } - if !md.is_file() { - return Err(format!( - "{}: external binary is not a regular file", - path.display() - )); - } - if md.uid() != 0 { - return Err(format!( - "{}: external binary owned by uid {} (expected root/0); refusing to trust", - path.display(), - md.uid() - )); - } - if md.mode() & 0o002 != 0 { - return Err(format!( - "{}: external binary is world-writable; refusing to trust", - path.display() - )); - } - } - Ok(()) -} - -/// Shell-identifier check shared with the Nix module's eval-time isIdent. -pub fn is_ident(k: &str) -> bool { - let mut cs = k.chars(); - matches!(cs.next(), Some(c) if c.is_ascii_alphabetic() || c == '_') - && cs.all(|c| c.is_ascii_alphanumeric() || c == '_') -} - -/// Decrypt one raw value: `encrypted:` via the ring (rotation-aware), -/// anything else passed through as opaque bytes (plaintext passthrough). -/// Base64 payload may contain ASCII whitespace (spaces, newlines, tabs, CR), -/// matching the lenient decoding for line-wrapped values. -pub fn decrypt_value( - env_file: &Path, - key: &str, - raw: &str, - ring: &KeyRing, - naming: KeyNaming, -) -> Result>, String> { - let Some(b64) = raw.strip_prefix("encrypted:") else { - return Ok(Zeroizing::new(raw.as_bytes().to_vec())); - }; - let ciphertext: Zeroizing> = { - if b64.chars().any(|c| c.is_ascii_whitespace()) { - // Zeroizing: b64_clean holds derived ciphertext material (base64 - // of the encrypted blob). Zeroize on drop for defense-in-depth, - // matching the crate's hygiene posture on key and plaintext buffers. - let b64_clean = Zeroizing::new( - b64.chars() - .filter(|c| !c.is_ascii_whitespace()) - .collect::(), - ); - Zeroizing::new( - BASE64 - .decode(&*b64_clean) - .map_err(|_| format!("{}: {key} is not valid base64", env_file.display()))?, - ) - } else { - Zeroizing::new( - BASE64 - .decode(b64) - .map_err(|_| format!("{}: {key} is not valid base64", env_file.display()))?, - ) - } - }; - let var = naming.key_var_for(env_file)?; - let candidates = ring - .0 - .get(&var) - .ok_or_else(|| format!("key ring has no {var} entry"))?; - for sk in candidates { - if let Ok(pt) = ecies::decrypt(&sk[..], &ciphertext) { - return Ok(Zeroizing::new(pt)); - } - } - Err(format!( - "{}: no key under {var} decrypts {key} ({} candidate(s) tried)", - env_file.display(), - candidates.len() - )) -} - -/// Resolve a single entry using the key ring. -/// Supports both encrypted values and plaintext passthrough. -pub fn resolve( - entry: &Entry, - ring: &KeyRing, - naming: KeyNaming, -) -> Result>, String> { - let iter = dotenvy::from_path_iter(&entry.env_file) - .map_err(|e| format!("{}: {e}", entry.env_file.display()))?; - // Last assignment wins, matching dotenv semantics within one file. - let mut found: Option> = None; - for item in iter { - let (k, v) = item.map_err(|e| format!("{}: {e}", entry.env_file.display()))?; - let v = Zeroizing::new(v); - if k == entry.key { - found = Some(v); - } - } - let raw = - found.ok_or_else(|| format!("{}: no key named {}", entry.env_file.display(), entry.key))?; - - decrypt_value(&entry.env_file, &entry.key, &raw, ring, naming) -} - -/// Resolved (name, secret-bytes) pairs, in injection order. -pub type ResolvedVars = Vec<(String, Zeroizing>)>; - -/// Resolve every key across `files` per the precedence contract -/// (see docs/src/launcher-contract.md): within one file the LAST assignment -/// wins (dotenv semantics); across files the FIRST file defining a key wins -/// unless `overload`; keys already present in the process environment are -/// skipped unless `overload`. Adapter metadata keys are dropped; -/// non-identifier keys are a hard error (they become env names/filenames). -pub fn resolve_all( - files: &[PathBuf], - ring: &KeyRing, - overload: bool, - strict: bool, - env_has: &dyn Fn(&str) -> bool, - naming: KeyNaming, -) -> Result { - let metadata_prefix = naming.metadata_prefix(); - let mut order: Vec = Vec::new(); - let mut merged: HashMap)> = HashMap::new(); - for f in files { - let iter = dotenvy::from_path_iter(f).map_err(|e| format!("{}: {e}", f.display()))?; - let mut file_vals: HashMap> = HashMap::new(); - let mut file_order: Vec = Vec::new(); - for item in iter { - let (k, v) = item.map_err(|e| format!("{}: {e}", f.display()))?; - let v = Zeroizing::new(v); - if let Some(prefix) = metadata_prefix - && k.starts_with(prefix) - { - continue; - } - if !is_ident(&k) { - return Err(format!( - "{}: refusing non-identifier key {k:?}", - f.display() - )); - } - if !file_vals.contains_key(&k) { - file_order.push(k.clone()); - } - file_vals.insert(k, v); // last assignment within a file wins - } - for k in file_order { - let v = file_vals.remove(&k).expect("key recorded in file_order"); - if let Some(slot) = merged.get_mut(&k) { - if overload { - *slot = (f.clone(), v); // later file wins under overload - } - } else { - order.push(k.clone()); - merged.insert(k, (f.clone(), v)); - } - } - } - let mut out = Vec::new(); - for k in order { - if !overload && env_has(&k) { - continue; // process environment wins - } - let (file, raw) = merged.remove(&k).expect("key recorded in order"); - match decrypt_value(&file, &k, &raw, ring, naming) { - Ok(v) => out.push((k, v)), - Err(e) if strict => return Err(e), - Err(e) => crate::server::log(&format!("non-strict: skipping {k}: {e}")), - } - } - Ok(out) -} - -#[cfg(test)] -#[allow(clippy::unwrap_used, clippy::panic, unused_qualifications)] -pub mod tests { - use super::*; - use crate::adapter::KeyNaming; - - /// Test secret key hex — never use outside tests. - pub const TEST_SK_HEX: &str = - "1111111111111111111111111111111111111111111111111111111111111111"; - - /// Build a test key ring with the test secret key under - /// `POSTMASTER_KEY` (for bundle adapter tests). - pub fn make_test_ring() -> KeyRing { - let pairs = vec![( - "POSTMASTER_KEY".to_string(), - Zeroizing::new(TEST_SK_HEX.to_string()), - )]; - KeyRing::from_pairs(pairs, KeyNaming::Bundle).unwrap() - } - use std::io::Write; - use std::path::Path; - - fn with_temp_keys(content: &str, f: impl FnOnce(&Path)) { - use std::os::unix::fs::PermissionsExt; - let dir = std::env::temp_dir(); - let path = dir.join(format!( - "postmaster-test-keys-{}-{:?}", - std::process::id(), - std::thread::current().id() - )); - { - let mut f = std::fs::File::create(&path).unwrap(); - writeln!(f, "{}", content).unwrap(); - } - // KeyRing::load now enforces 0600-or-stricter permissions (audit - // finding #1). The temp file must pass that check. - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap(); - f(&path); - let _ = std::fs::remove_file(&path); - } - - fn tdir(tag: &str) -> std::path::PathBuf { - let d = std::env::temp_dir().join(format!("pm-keys-{tag}-{}", std::process::id())); - let _ = std::fs::remove_dir_all(&d); - std::fs::create_dir_all(&d).unwrap(); - d - } - - #[test] - fn key_var_for_basic() { - assert_eq!( - KeyNaming::Env - .key_var_for(std::path::Path::new(".env")) - .unwrap(), - "DOTENV_PRIVATE_KEY" - ); - assert_eq!( - KeyNaming::Env - .key_var_for(std::path::Path::new(".env.production")) - .unwrap(), - "DOTENV_PRIVATE_KEY_PRODUCTION" - ); - assert_eq!( - KeyNaming::Env - .key_var_for(std::path::Path::new(".env.staging_v2")) - .unwrap(), - "DOTENV_PRIVATE_KEY_STAGING_V2" - ); - } - - #[test] - fn load_rotated_keys_and_plaintext_env() { - // Create a real .env file with a plaintext value (simulating --plain) - let env_dir = std::env::temp_dir(); - let env_path = env_dir.join(format!( - "postmaster-test-env-{}-{:?}", - std::process::id(), - std::thread::current().id() - )); - { - let mut f = std::fs::File::create(&env_path).unwrap(); - writeln!(f, "PLAIN=hello-world").unwrap(); - } - - let entry = Entry { - env_file: env_path.clone(), - key: "PLAIN".to_string(), - peer_user: None, - }; - // Ring can be empty for plaintext path - let ring = KeyRing(HashMap::new()); - let result = resolve(&entry, &ring, KeyNaming::Env).unwrap(); - assert_eq!(&*result, b"hello-world"); - - let _ = std::fs::remove_file(&env_path); - } - - #[test] - fn from_pairs_filters_and_rotates() { - let ring = KeyRing::from_pairs( - [ - ("UNRELATED".to_string(), Zeroizing::new("x".to_string())), - ( - "DOTENV_PRIVATE_KEY_PRODUCTION".to_string(), - Zeroizing::new(format!("{},{}", "22".repeat(32), "33".repeat(32))), - ), - ], - KeyNaming::Env, - ) - .unwrap(); - assert_eq!(ring.0.len(), 1); - assert_eq!(ring.0["DOTENV_PRIVATE_KEY_PRODUCTION"].len(), 2); - } - - #[test] - fn from_pairs_empty_is_error() { - assert!( - KeyRing::from_pairs( - [("A".to_string(), Zeroizing::new("b".to_string()))], - KeyNaming::Env - ) - .is_err() - ); - } - - #[test] - fn load_rejects_bad_hex() { - let content = "DOTENV_PRIVATE_KEY=not-hex\n"; - with_temp_keys(content, |p| match KeyRing::load(p, KeyNaming::Env) { - Err(e) if e.contains("not valid hex") => {} - other => panic!("expected bad hex error, got {other:?}"), - }); - } - - #[test] - fn load_rejects_world_readable_keys_file() { - use std::os::unix::fs::PermissionsExt; - let dir = std::env::temp_dir(); - let path = dir.join(format!( - "postmaster-test-keys-worldread-{}-{:?}", - std::process::id(), - std::thread::current().id() - )); - { - let mut f = std::fs::File::create(&path).unwrap(); - writeln!(f, "DOTENV_PRIVATE_KEY={}", "11".repeat(32)).unwrap(); - } - // 0644: world-readable — must be rejected. - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap(); - match KeyRing::load(&path, KeyNaming::Env) { - Err(e) if e.contains("group/world accessible") => {} - other => panic!("expected group/world permission error, got {other:?}"), - } - let _ = std::fs::remove_file(&path); - } - - #[test] - fn load_rejects_group_readable_keys_file() { - use std::os::unix::fs::PermissionsExt; - let dir = std::env::temp_dir(); - let path = dir.join(format!( - "postmaster-test-keys-groupread-{}-{:?}", - std::process::id(), - std::thread::current().id() - )); - { - let mut f = std::fs::File::create(&path).unwrap(); - writeln!(f, "DOTENV_PRIVATE_KEY={}", "11".repeat(32)).unwrap(); - } - // 0640: group-readable — must be rejected. - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o640)).unwrap(); - match KeyRing::load(&path, KeyNaming::Env) { - Err(e) if e.contains("group/world accessible") => {} - other => panic!("expected group permission error, got {other:?}"), - } - let _ = std::fs::remove_file(&path); - } - - #[test] - fn load_rejects_symlink_keys_file() { - let dir = tdir("symlink-keys"); - let real = dir.join("real-keys"); - std::fs::write(&real, format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32))).unwrap(); - use std::os::unix::fs::PermissionsExt; - std::fs::set_permissions(&real, std::fs::Permissions::from_mode(0o600)).unwrap(); - let link = dir.join(".env.keys"); - std::os::unix::fs::symlink(&real, &link).unwrap(); - match KeyRing::load(&link, KeyNaming::Env) { - Err(e) if e.contains("symlink") => {} - other => panic!("expected symlink rejection error, got {other:?}"), - } - } - - #[test] - fn load_accepts_0600_keys_file() { - // Sanity: a properly locked-down keys file (0600, owned by euid) - // loads normally. This guards against false positives from the - // permission and ownership checks. - let content = format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32)); - with_temp_keys(&content, |p| { - KeyRing::load(p, KeyNaming::Env).expect("0600 keys file owned by euid should load"); - }); - } - - #[test] - fn load_accepts_0400_keys_file() { - use std::os::unix::fs::PermissionsExt; - let dir = std::env::temp_dir(); - let path = dir.join(format!( - "postmaster-test-keys-0400-{}-{:?}", - std::process::id(), - std::thread::current().id() - )); - { - let mut f = std::fs::File::create(&path).unwrap(); - writeln!(f, "DOTENV_PRIVATE_KEY={}", "11".repeat(32)).unwrap(); - } - // 0400: read-only by owner — stricter than 0600, must pass. - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o400)).unwrap(); - KeyRing::load(&path, KeyNaming::Env).expect("0400 keys file owned by euid should load"); - let _ = std::fs::remove_file(&path); - } - - #[test] - #[cfg(target_os = "macos")] - fn verify_external_binary_accepts_codesigned_binary() { - // /usr/bin/security is Apple-signed and SIP-protected; the codesign - // verification must pass. This guards against a hypothetical SIP - // bypass or a misconfigured environment where the binary has been - // replaced. - verify_external_binary(std::path::Path::new("/usr/bin/security")) - .expect("codesigned system binary should pass verification"); - } - - #[test] - #[cfg(target_os = "macos")] - fn verify_external_binary_rejects_unsigned_file() { - // A temp file with no code signature must be rejected by codesign -v. - let dir = std::env::temp_dir(); - let path = dir.join(format!( - "postmaster-test-unsigned-{}-{:?}", - std::process::id(), - std::thread::current().id() - )); - std::fs::write(&path, b"not a signed binary").unwrap(); - let result = verify_external_binary(&path); - let _ = std::fs::remove_file(&path); - assert!( - result.is_err(), - "unsigned file should fail code signature verification" - ); - } - - #[test] - #[cfg(not(target_os = "macos"))] - fn verify_external_binary_rejects_non_root_owned() { - // On Linux, a non-root-owned binary in /tmp must be rejected. - let dir = std::env::temp_dir(); - let path = dir.join(format!( - "postmaster-test-binary-{}-{:?}", - std::process::id(), - std::thread::current().id() - )); - std::fs::write(&path, b"fake binary").unwrap(); - use std::os::unix::fs::PermissionsExt; - std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap(); - let result = verify_external_binary(&path); - let _ = std::fs::remove_file(&path); - assert!(result.is_err(), "non-root-owned binary should be rejected"); - } - - #[test] - fn is_ident_rules() { - assert!(is_ident("DATABASE_URL") && is_ident("_x9")); - assert!(!is_ident("9x") && !is_ident("a-b") && !is_ident("") && !is_ident("a b")); - } - - #[test] - fn resolve_all_precedence() { - let d = tdir("prec"); - std::fs::write( - d.join(".env"), - "A=first\nB=one\nB=two\nDOTENV_PUBLIC_KEY=zz\n", - ) - .unwrap(); - std::fs::write(d.join(".env.local"), "A=second\nC=three\n").unwrap(); - let files = [d.join(".env"), d.join(".env.local")]; - let ring = KeyRing(HashMap::new()); - - // default: first file wins; within a file last assignment wins; - // process-env presence suppresses; DOTENV_* filtered. - let out = resolve_all(&files, &ring, false, true, &|k| k == "C", KeyNaming::Env).unwrap(); - let got: Vec<(&str, &[u8])> = out.iter().map(|(k, v)| (k.as_str(), &v[..])).collect(); - assert_eq!( - got, - vec![("A", b"first".as_slice()), ("B", b"two".as_slice())] - ); - - // overload: later file wins, env presence ignored. - let out = resolve_all(&files, &ring, true, true, &|k| k == "C", KeyNaming::Env).unwrap(); - let got: Vec<(&str, &[u8])> = out.iter().map(|(k, v)| (k.as_str(), &v[..])).collect(); - assert_eq!( - got, - vec![ - ("A", b"second".as_slice()), - ("B", b"two".as_slice()), - ("C", b"three".as_slice()) - ] - ); - } - - #[test] - fn resolve_all_rejects_non_identifier() { - // dotenvy rejects keys starting with `-` or digit during parsing, but accepts `.` - // in subsequent characters (e.g., BAD.KEY=x parses fine). Our is_ident check rejects - // `.` in all positions, so a dotted key exercises the rejection branch in resolve_all. - let d = tdir("ident"); - std::fs::write(d.join(".env"), "BAD.KEY=x\n").unwrap(); - let ring = KeyRing(HashMap::new()); - let e = resolve_all( - &[d.join(".env")], - &ring, - false, - true, - &|_| false, - KeyNaming::Env, - ) - .unwrap_err(); - assert!(e.contains("non-identifier"), "{e}"); - } - - #[test] - fn resolve_all_strict_fails_on_undecryptable() { - let d = tdir("strict"); - std::fs::write(d.join(".env"), "A=encrypted:!!!notbase64\n").unwrap(); - let ring = KeyRing(HashMap::new()); - assert!( - resolve_all( - &[d.join(".env")], - &ring, - false, - true, - &|_| false, - KeyNaming::Env - ) - .is_err() - ); - // non-strict: skipped, not served wrong. - let out = resolve_all( - &[d.join(".env")], - &ring, - false, - false, - &|_| false, - KeyNaming::Env, - ) - .unwrap(); - assert!(out.is_empty()); - } - - #[test] - fn from_env_loads_and_fails_closed() { - // from_env reads ALL DOTENV_PRIVATE_KEY* vars from the process - // environment and delegates to from_pairs. This is a single test - // (not two) because env mutation is global and tests run in - // parallel — two tests mutating DOTENV_PRIVATE_KEY* simultaneously - // would race. Using a unique suffix to avoid collision with any - // ambient vars in the test runner. - let var_name = "DOTENV_PRIVATE_KEY_TESTFROMENV"; - let key_hex = "aa".repeat(32); - - // Positive path: set a valid key, from_env succeeds. - // SAFETY: set_var/remove_var are unsafe on edition 2024 (not - // thread-safe). This test does not spawn threads and the var name - // is unique, so no concurrent test mutates the same var. - unsafe { - std::env::set_var(var_name, &key_hex); - } - let ring = KeyRing::from_env(KeyNaming::Env); - unsafe { - std::env::remove_var(var_name); - } - let ring = ring.expect("from_env should succeed with a valid key set"); - let candidates = ring - .0 - .get(var_name) - .expect("ring should contain the key we set"); - assert_eq!(candidates.len(), 1, "exactly one candidate expected"); - assert_eq!(&candidates[0][..], &[0xaa; 32]); - - // Negative path: set an invalid hex value, from_env fails closed - // with an "environment:" prefixed error. - unsafe { - std::env::set_var(var_name, "not-valid-hex-at-all"); - } - let err = KeyRing::from_env(KeyNaming::Env); - unsafe { - std::env::remove_var(var_name); - } - let err = err.expect_err("from_env should fail on invalid hex"); - assert!( - err.starts_with("environment:"), - "expected 'environment:' prefix, got: {err}" - ); - - // Also verify the from_pairs empty-error path directly: no - // DOTENV_PRIVATE_KEY* entries at all should be an error. - assert!( - KeyRing::from_pairs( - [( - "NOT_A_DOTENV_KEY".to_string(), - Zeroizing::new("x".to_string()) - )], - KeyNaming::Env, - ) - .is_err() - ); - } -} diff --git a/src/keys/dotenv.rs b/src/keys/dotenv.rs new file mode 100644 index 0000000..9107c1c --- /dev/null +++ b/src/keys/dotenv.rs @@ -0,0 +1,568 @@ +//! Dotenv syntax from dotenvy 0.15.7 with bounded expansion and redacted errors. +//! MIT notice: `licenses/dotenvy-MIT.txt`. + +use std::io::{BufRead, BufReader}; +use std::path::Path; + +use std::collections::HashMap; +use std::env; + +use zeroize::Zeroizing; + +type Result = std::result::Result; +const INVALID: &str = "invalid dotenv syntax"; +const LIMIT: &str = "dotenv resource limit exceeded"; +const MAX_VALUE_BYTES: usize = 16 * 1024 * 1024; +const MAX_PARSED_BYTES: usize = 64 * 1024 * 1024; +const MAX_ENTRIES: usize = 65_536; + +type ParsedLine = Result)>>; + +fn parse_line( + line: &str, + substitution_data: &mut HashMap>>, + budget: &mut Budget, +) -> ParsedLine { + let mut parser = LineParser::new(line, substitution_data, budget); + parser.parse_line() +} + +struct LineParser<'parse> { + substitution_data: &'parse mut HashMap>>, + line: &'parse str, + budget: &'parse mut Budget, +} + +impl<'parse> LineParser<'parse> { + fn new( + line: &'parse str, + substitution_data: &'parse mut HashMap>>, + budget: &'parse mut Budget, + ) -> LineParser<'parse> { + LineParser { + substitution_data, + line: line.trim_end(), + budget, + } + } + + fn parse_line(&mut self) -> ParsedLine { + self.skip_whitespace(); + // if its an empty line or a comment, skip it + if self.line.is_empty() || self.line.starts_with('#') { + return Ok(None); + } + + self.budget.entry()?; + let mut key = self.parse_key()?; + self.skip_whitespace(); + + // export can be either an optional prefix or a key itself + if key == "export" { + // here we check for an optional `=`, below we throw directly when it’s not found. + if self.expect_equal().is_err() { + key = self.parse_key()?; + self.skip_whitespace(); + self.expect_equal()?; + } + } else { + self.expect_equal()?; + } + self.skip_whitespace(); + + if self.line.is_empty() || self.line.starts_with('#') { + self.budget.retain(key.len())?; + self.substitution_data.insert(key.clone(), None); + return Ok(Some((key, Zeroizing::new(String::new())))); + } + + let parsed_value = parse_value(self.line, self.substitution_data)?; + self.budget.retain(key.len() + parsed_value.len())?; + self.substitution_data + .insert(key.clone(), Some(parsed_value.clone())); + + Ok(Some((key, parsed_value))) + } + + fn parse_key(&mut self) -> Result { + if !self + .line + .starts_with(|c: char| c.is_ascii_alphabetic() || c == '_') + { + return Err(INVALID); + } + let index = match self + .line + .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_' || c == '.')) + { + Some(index) => index, + None => self.line.len(), + }; + let key = String::from(&self.line[..index]); + self.line = &self.line[index..]; + Ok(key) + } + + fn expect_equal(&mut self) -> Result<()> { + if !self.line.starts_with('=') { + return Err(INVALID); + } + self.line = &self.line[1..]; + Ok(()) + } + + fn skip_whitespace(&mut self) { + if let Some(index) = self.line.find(|c: char| !c.is_whitespace()) { + self.line = &self.line[index..]; + } else { + self.line = ""; + } + } +} + +#[derive(Eq, PartialEq)] +enum SubstitutionMode { + None, + Block, + EscapedBlock, +} + +fn parse_value( + input: &str, + substitution_data: &mut HashMap>>, +) -> Result> { + let mut strong_quote = false; // ' + let mut weak_quote = false; // " + let mut escaped = false; + let mut expecting_end = false; + + let mut output = Zeroizing::new(String::new()); + + let mut substitution_mode = SubstitutionMode::None; + let mut substitution_name = String::new(); + + for c in input.chars() { + // A whitespace-separated comment ends the value; an attached # stays literal. + if expecting_end { + if c == ' ' || c == '\t' { + continue; + } else if c == '#' { + break; + } else { + return Err(INVALID); + } + } else if escaped { + match c { + '\\' | '\'' | '"' | '$' | ' ' => push_char(&mut output, c)?, + 'n' => push_char(&mut output, '\n')?, // handle \n case + _ => { + return Err(INVALID); + } + } + + escaped = false; + } else if strong_quote { + if c == '\'' { + strong_quote = false; + } else { + push_char(&mut output, c)?; + } + } else if substitution_mode != SubstitutionMode::None { + if c.is_alphanumeric() { + substitution_name.push(c); + } else { + match substitution_mode { + SubstitutionMode::None => unreachable!(), + SubstitutionMode::Block => { + if c == '{' && substitution_name.is_empty() { + substitution_mode = SubstitutionMode::EscapedBlock; + } else { + apply_substitution(substitution_data, &substitution_name, &mut output)?; + substitution_name.clear(); + if c == '$' { + substitution_mode = if !strong_quote && !escaped { + SubstitutionMode::Block + } else { + SubstitutionMode::None + } + } else { + substitution_mode = SubstitutionMode::None; + push_char(&mut output, c)?; + } + } + } + SubstitutionMode::EscapedBlock => { + if c == '}' { + substitution_mode = SubstitutionMode::None; + apply_substitution(substitution_data, &substitution_name, &mut output)?; + substitution_name.clear(); + } else { + substitution_name.push(c); + } + } + } + } + } else if c == '$' { + substitution_mode = if !strong_quote && !escaped { + SubstitutionMode::Block + } else { + SubstitutionMode::None + } + } else if weak_quote { + if c == '"' { + weak_quote = false; + } else if c == '\\' { + escaped = true; + } else { + push_char(&mut output, c)?; + } + } else if c == '\'' { + strong_quote = true; + } else if c == '"' { + weak_quote = true; + } else if c == '\\' { + escaped = true; + } else if c == ' ' || c == '\t' { + expecting_end = true; + } else { + push_char(&mut output, c)?; + } + } + + if substitution_mode == SubstitutionMode::EscapedBlock || strong_quote || weak_quote { + Err(INVALID) + } else { + apply_substitution(substitution_data, &substitution_name, &mut output)?; + Ok(output) + } +} + +fn apply_substitution( + substitution_data: &HashMap>>, + substitution_name: &str, + output: &mut String, +) -> Result<()> { + if let Ok(value) = env::var(substitution_name) { + let value = Zeroizing::new(value); + push_str(output, &value)?; + } else if let Some(Some(value)) = substitution_data.get(substitution_name) { + push_str(output, value)?; + } + Ok(()) +} + +fn push_str(output: &mut String, value: &str) -> Result<()> { + if value.len() > MAX_VALUE_BYTES.saturating_sub(output.len()) { + return Err(LIMIT); + } + output.push_str(value); + Ok(()) +} + +fn push_char(output: &mut String, value: char) -> Result<()> { + let mut bytes = [0; 4]; + push_str(output, value.encode_utf8(&mut bytes)) +} +struct QuotedLines { + buf: B, +} + +enum ParseState { + Complete, + Escape, + StrongOpen, + StrongOpenEscape, + WeakOpen, + WeakOpenEscape, + Comment, + WhiteSpace, +} + +fn eval_end_state(prev_state: ParseState, buf: &str) -> (usize, ParseState) { + let mut cur_state = prev_state; + let mut cur_pos: usize = 0; + + for (pos, c) in buf.char_indices() { + cur_pos = pos; + cur_state = match cur_state { + ParseState::WhiteSpace => match c { + '#' => return (cur_pos, ParseState::Comment), + '\\' => ParseState::Escape, + '"' => ParseState::WeakOpen, + '\'' => ParseState::StrongOpen, + _ => ParseState::Complete, + }, + ParseState::Escape => ParseState::Complete, + ParseState::Complete => match c { + c if c.is_whitespace() && c != '\n' && c != '\r' => ParseState::WhiteSpace, + '\\' => ParseState::Escape, + '"' => ParseState::WeakOpen, + '\'' => ParseState::StrongOpen, + _ => ParseState::Complete, + }, + ParseState::WeakOpen => match c { + '\\' => ParseState::WeakOpenEscape, + '"' => ParseState::Complete, + _ => ParseState::WeakOpen, + }, + ParseState::WeakOpenEscape => ParseState::WeakOpen, + ParseState::StrongOpen => match c { + '\\' => ParseState::StrongOpenEscape, + '\'' => ParseState::Complete, + _ => ParseState::StrongOpen, + }, + ParseState::StrongOpenEscape => ParseState::StrongOpen, + // Comments last the entire line. + ParseState::Comment => return (cur_pos, ParseState::Comment), + }; + } + (cur_pos, cur_state) +} + +impl Iterator for QuotedLines { + type Item = Result>; + + fn next(&mut self) -> Option>> { + let mut buf = Zeroizing::new(String::new()); + let mut cur_state = ParseState::Complete; + let mut buf_pos; + let mut cur_pos; + loop { + buf_pos = buf.len(); + match self.buf.read_line(&mut buf) { + Ok(0) => match cur_state { + ParseState::Complete => return None, + _ => { + return Some(Err(INVALID)); + } + }, + Ok(_n) => { + // Skip lines which start with a # before iteration + // This optimizes parsing a bit. + if buf.trim_start().starts_with('#') { + return Some(Ok(Zeroizing::new(String::new()))); + } + let result = eval_end_state(cur_state, &buf[buf_pos..]); + cur_pos = result.0; + cur_state = result.1; + + match cur_state { + ParseState::Complete => { + if buf.ends_with('\n') { + buf.pop(); + if buf.ends_with('\r') { + buf.pop(); + } + } + return Some(Ok(buf)); + } + ParseState::Escape + | ParseState::StrongOpen + | ParseState::StrongOpenEscape + | ParseState::WeakOpen + | ParseState::WeakOpenEscape + | ParseState::WhiteSpace => {} + ParseState::Comment => { + buf.truncate(buf_pos + cur_pos); + return Some(Ok(buf)); + } + } + } + Err(_) => return Some(Err(INVALID)), + } + } + } +} + +/// Cumulative work across every dotenv file, including shadowed and metadata entries. +#[derive(Default)] +pub(super) struct Budget { + entries: usize, + bytes: usize, + input_bytes: usize, +} + +impl Budget { + fn entry(&mut self) -> Result<()> { + if self.entries == MAX_ENTRIES { + return Err(LIMIT); + } + self.entries += 1; + Ok(()) + } + + fn retain(&mut self, bytes: usize) -> Result<()> { + if bytes > MAX_PARSED_BYTES.saturating_sub(self.bytes) { + return Err(LIMIT); + } + self.bytes += bytes; + Ok(()) + } +} + +/// Read a regular, non-symlink file with a byte cap, then parse with bounded substitutions. +pub(super) fn read( + path: &Path, + budget: &mut Budget, + authorized: Option<&[[u8; 32]]>, +) -> std::result::Result)>, String> { + use rustix::fs::{FileType, Mode, OFlags, fstat, open}; + let fd = open( + path, + OFlags::RDONLY | OFlags::NONBLOCK | OFlags::NOFOLLOW | OFlags::CLOEXEC, + Mode::empty(), + ) + .map_err(|e| format!("{}: {e} (refusing to follow a symlink)", path.display()))?; + let stat = fstat(&fd).map_err(|e| format!("{}: stat: {e}", path.display()))?; + if FileType::from_raw_mode(stat.st_mode) != FileType::RegularFile { + return Err(format!("{}: not a regular file", path.display())); + } + let raw = Zeroizing::new(crate::server::read_capped(std::fs::File::from(fd), path)?); + if raw.len() > MAX_PARSED_BYTES.saturating_sub(budget.input_bytes) { + return Err(format!("{}: {LIMIT}", path.display())); + } + budget.input_bytes += raw.len(); + if let Some(authorized) = authorized { + use sha2::Digest as _; + let hash: [u8; 32] = sha2::Sha256::digest(&raw).into(); + if !authorized.contains(&hash) { + return Err(format!( + "{}: dotenv source is not authorized", + path.display() + )); + } + } + parse(&raw, budget).map_err(|e| format!("{}: {e}", path.display())) +} + +fn parse(raw: &[u8], budget: &mut Budget) -> Result)>> { + let lines = QuotedLines { + buf: BufReader::new(raw), + }; + let mut substitutions = HashMap::new(); + let mut values = Vec::new(); + for line in lines { + if let Some(pair) = parse_line(&line?, &mut substitutions, budget)? { + values.push(pair); + } + } + Ok(values) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic)] +mod tests { + use super::*; + + #[test] + fn matches_dotenv_grammar_and_substitution() { + let _guard = crate::test_util::ENV_LOCK.lock().unwrap(); + let corpus = [ + "", + "# comment\n", + "A=\n", + "export A=one\n", + "export=one\n", + "A=one#two\n", + "A=one # two\n", + "A='one\ntwo'\n", + "A=\"one\\ntwo\"\n", + "A=one\\ two\n", + "A='x'\"y\"z\n", + "A=x\nB=${A}${A}\n", + "A=x\nA=y\nB=$A\n", + "A=x\nB=$A-$A\n", + "A=x\nB=\"${A}z\"\n", + "A=x\nB='${A}'\n", + "A=x\nB=\\$A\n", + "A=x\nB=${MISSING}\n", + "A=\nB=${A}\n", + "A=x\nB=$A$A\n", + "A=x\nB=${A}\nC=${B}\n", + "A=\"unterminated", + "A=one two\n", + "A='unterminated", + "A=\"bad\\q\"\n", + "A=${oops\n", + "1A=x\n", + "A.B=x\n", + "A=x\r\nB=y\r\n", + "\u{feff}A=x\n", + "A=x\\\n", + "A=\"x\n# inside\ny\"\n", + "A=\"x\" trailing\n", + "A=\"λ\"\n", + "A=${PATH}\n", + "A='x\\'\n", + "A=x \nB=y\n", + ]; + for input in corpus { + let expected = dotenvy::from_read_iter(input.as_bytes()) + .collect::, _>>(); + let actual = parse(input.as_bytes(), &mut Budget::default()); + match (expected, actual) { + (Ok(expected), Ok(actual)) => assert_eq!( + expected, + actual + .into_iter() + .map(|(k, v)| (k, (*v).clone())) + .collect::>(), + "{input:?}" + ), + (Err(_), Err(INVALID)) => {} + _ => panic!("parser outcome differs for {input:?}"), + } + } + } + + #[test] + fn bounds_expansion_and_counts_shadowed_metadata() { + let mut input = "A0=x\n".to_string(); + for i in 1..40 { + input.push_str(&format!("A{i}=${{A{}}}${{A{}}}\n", i - 1, i - 1)); + } + assert!(input.len() < 2048); + assert_eq!( + parse(input.as_bytes(), &mut Budget::default()).unwrap_err(), + LIMIT + ); + let input = "DOTENV_METADATA=\n".repeat(MAX_ENTRIES + 1); + assert_eq!( + parse(input.as_bytes(), &mut Budget::default()).unwrap_err(), + LIMIT + ); + let mut budget = Budget { + bytes: MAX_PARSED_BYTES, + ..Budget::default() + }; + assert_eq!(parse(b"A=x\n", &mut budget).unwrap_err(), LIMIT); + } + + #[test] + fn rejects_special_and_oversized_sources() { + let dir = crate::test_util::temp_dir::TestDir::new("dotenv-source"); + let fifo = dir.join("fifo"); + assert!( + std::process::Command::new("mkfifo") + .arg(&fifo) + .status() + .unwrap() + .success() + ); + assert!( + read(&fifo, &mut Budget::default(), None) + .unwrap_err() + .contains("not a regular file") + ); + let path = dir.join("large"); + std::fs::File::create(&path) + .unwrap() + .set_len(16 * 1024 * 1024 + 1) + .unwrap(); + assert!( + read(&path, &mut Budget::default(), None) + .unwrap_err() + .contains("size cap") + ); + } +} diff --git a/src/keys/env.rs b/src/keys/env.rs new file mode 100644 index 0000000..b0fecae --- /dev/null +++ b/src/keys/env.rs @@ -0,0 +1,157 @@ +//! Process-environment key source (external provisioning). + +use zeroize::Zeroizing; + +use super::KeyRing; +use crate::adapter::KeyNaming; + +/// True for exactly `PREFIX` or `PREFIX_`. A bare +/// prefix match would slurp unrelated variables like +/// `DOTENV_PRIVATE_KEYFOO` as key material. +pub(crate) fn is_key_var_name(prefix: &str, name: &str) -> bool { + name == prefix + || name + .strip_prefix(prefix) + .is_some_and(|rest| rest.len() > 1 && rest.starts_with('_')) +} + +/// Whether `name` is a private-key variable for any supported adapter. +pub(crate) fn is_private_key_var_name(name: &str) -> bool { + [KeyNaming::Env, KeyNaming::Bundle] + .into_iter() + .any(|n| is_key_var_name(n.key_prefix(), name)) +} + +/// Implementation of [`KeyRing::from_env`]; the contract is documented on +/// the method. +pub(super) fn from_env(namings: &[KeyNaming]) -> Result { + // vars_os + skip non-UTF-8 names/values: std::env::vars() PANICS during iteration + // if any inherited entry is not valid Unicode, which under panic=abort aborts the + // whole launcher on an arbitrary inherited variable. Key-var names match + // [A-Za-z0-9_] and key values are hex, so nothing admissible is lost. + KeyRing::from_pairs( + std::env::vars_os() + .filter_map(|(k, v)| Some((k.into_string().ok()?, v.into_string().ok()?))) + .filter(|(k, _)| namings.iter().any(|n| is_key_var_name(n.key_prefix(), k))) + .map(|(k, v)| (k, Zeroizing::new(v))), + namings, + ) + .map_err(|e| format!("environment: {e}")) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic, unused_qualifications)] +mod tests { + use super::*; + use crate::test_util::ENV_LOCK; + + #[test] + fn is_key_var_name_rules() { + // Only `PREFIX` or `PREFIX_` match; prefix-substring collisions are + // rejected. + let p = "DOTENV_PRIVATE_KEY"; + assert!(is_key_var_name(p, "DOTENV_PRIVATE_KEY")); + assert!(is_key_var_name(p, "DOTENV_PRIVATE_KEY_PRODUCTION")); + assert!(!is_key_var_name(p, "DOTENV_PRIVATE_KEYFOO")); + assert!(!is_key_var_name(p, "DOTENV_PRIVATE_KEY_")); // empty suffix + assert!(!is_key_var_name(p, "DOTENV_PRIVATE_KE")); + assert!(!is_key_var_name(p, "XDOTENV_PRIVATE_KEY")); + } + + #[test] + fn from_env_loads_and_fails_closed() { + // from_env reads ALL DOTENV_PRIVATE_KEY* vars from the process + // environment and delegates to from_pairs. This is a single test + // (not two) because env mutation is global; the shared ENV_LOCK + // serializes it against every other env-mutating test. Using a + // unique suffix to avoid collision with any ambient vars in the + // test runner. + // + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + let var_name = "DOTENV_PRIVATE_KEY_TESTFROMENV"; + let key_hex = "aa".repeat(32); + + // Positive path: set a valid key, from_env succeeds. + unsafe { + std::env::set_var(var_name, &key_hex); + } + let ring = KeyRing::from_env(&[KeyNaming::Env]); + unsafe { + std::env::remove_var(var_name); + } + let ring = ring.expect("from_env should succeed with a valid key set"); + let candidates = ring + .0 + .get(var_name) + .expect("ring should contain the key we set"); + assert_eq!(candidates.len(), 1, "exactly one candidate expected"); + assert_eq!(&candidates[0][..], &[0xaa; 32]); + + // Negative path: set an invalid hex value, from_env fails closed + // with an "environment:" prefixed error. + unsafe { + std::env::set_var(var_name, "not-valid-hex-at-all"); + } + let err = KeyRing::from_env(&[KeyNaming::Env]); + unsafe { + std::env::remove_var(var_name); + } + let err = err.expect_err("from_env should fail on invalid hex"); + assert!( + err.starts_with("environment:"), + "expected 'environment:' prefix, got: {err}" + ); + + // Also verify the from_pairs empty-error path directly: no + // DOTENV_PRIVATE_KEY* entries at all should be an error. + assert!( + KeyRing::from_pairs( + [( + "NOT_A_DOTENV_KEY".to_string(), + Zeroizing::new("x".to_string()) + )], + &[KeyNaming::Env], + ) + .is_err() + ); + } + + #[test] + fn from_env_admits_only_the_required_namings() { + // The bundle-ring gap fix: with Bundle required, POSTMASTER_KEY + // enters the ring; when it is not required, the same variable is + // NOT admitted (least privilege). + // + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + let dotenv_var = "DOTENV_PRIVATE_KEY_TESTNAMINGS"; + let bundle_var = "POSTMASTER_KEY_TESTNAMINGS"; + let key_hex = "aa".repeat(32); + unsafe { + std::env::set_var(dotenv_var, &key_hex); + std::env::set_var(bundle_var, &key_hex); + } + let both = KeyRing::from_env(&[KeyNaming::Env, KeyNaming::Bundle]); + let bundle_only = KeyRing::from_env(&[KeyNaming::Bundle]); + unsafe { + std::env::remove_var(dotenv_var); + std::env::remove_var(bundle_var); + } + + let both = both.expect("both namings required should load"); + assert!(both.candidates(dotenv_var).is_some()); + assert!(both.candidates(bundle_var).is_some()); + + let bundle_only = bundle_only.expect("bundle naming alone should load"); + assert!( + bundle_only.candidates(dotenv_var).is_none(), + "an unrequired naming must not enter the ring" + ); + assert!(bundle_only.candidates(bundle_var).is_some()); + } +} diff --git a/src/keys/keychain.rs b/src/keys/keychain.rs new file mode 100644 index 0000000..b7685a7 --- /dev/null +++ b/src/keys/keychain.rs @@ -0,0 +1,33 @@ +//! macOS Keychain source using the default keychain search list. + +use zeroize::Zeroizing; + +use super::KeyRing; +use crate::adapter::KeyNaming; + +/// Implementation of [`KeyRing::from_keychain`]; the contract is +/// documented on the method. +#[cfg(target_os = "macos")] +pub(super) fn from_keychain( + service: &str, + vars: &[String], + namings: &[KeyNaming], +) -> Result { + // Reads go through the Security.framework API, not the /usr/bin/security CLI: no + // subprocess, no argv, and no stdout buffer holding key material — the + // UTF-8-failure path validates from a borrow so the error never carries the bytes. + let mut pairs = Vec::new(); + for var in vars { + let bytes = Zeroizing::new( + security_framework::passwords::get_generic_password(service, var).map_err(|_| { + format!("keychain {service}: no item for account {var} (fail closed)") + })?, + ); + let s = std::str::from_utf8(&bytes[..]) + .map_err(|_| format!("keychain {service}/{var}: not UTF-8"))?; + // from_pairs trims each comma-separated candidate itself, so + // no separate trim is needed here. + pairs.push((var.clone(), Zeroizing::new(s.to_string()))); + } + KeyRing::from_pairs(pairs, namings).map_err(|e| format!("keychain {service}: {e}")) +} diff --git a/src/keys/load.rs b/src/keys/load.rs new file mode 100644 index 0000000..e691523 --- /dev/null +++ b/src/keys/load.rs @@ -0,0 +1,260 @@ +//! `.env.keys` loading with type, ownership, and access checks on the opened inode. + +use std::path::Path; + +use zeroize::Zeroizing; + +use super::KeyRing; +use crate::adapter::KeyNaming; + +/// Implementation of [`KeyRing::load`]; the contract is documented on the +/// method. +pub(super) fn load(path: &Path, namings: &[KeyNaming]) -> Result { + // NONBLOCK is inert on regular files; on a FIFO it turns the otherwise blocking + // open into an immediate success that the file-type check below rejects — a FIFO + // here must never hang the launcher at open. + let oflags = rustix::fs::OFlags::RDONLY + | rustix::fs::OFlags::NOFOLLOW + | rustix::fs::OFlags::CLOEXEC + | rustix::fs::OFlags::NONBLOCK; + let fd = rustix::fs::open(path, oflags, rustix::fs::Mode::empty()).map_err(|e| { + format!( + "keys file {}: {e} (refusing to follow a symlink)", + path.display() + ) + })?; + let stat = + rustix::fs::fstat(&fd).map_err(|e| format!("keys file {}: fstat: {e}", path.display()))?; + // Regular files only: Mode carries no S_IFMT bits, so a directory would pass the + // permission mask below and fail later with an opaque parse error. + if !rustix::fs::FileType::from_raw_mode(stat.st_mode).is_file() { + return Err(format!( + "keys file {}: not a regular file (fail closed)", + path.display() + )); + } + let mode = rustix::fs::Mode::from_bits_truncate(stat.st_mode); + // Reject group or world accessibility. 0o077 masks both RWXG and RWXO. + if mode.intersects(rustix::fs::Mode::RWXG | rustix::fs::Mode::RWXO) { + return Err(format!( + "keys file {}: permissions {:#o} are group/world accessible; expected 0400 or 0600 (fail closed)", + path.display(), + stat.st_mode + )); + } + let euid = rustix::process::geteuid().as_raw(); + if stat.st_uid != euid { + return Err(format!( + "keys file {}: owned by uid {} but postmaster euid is {euid} (fail closed)", + path.display(), + stat.st_uid + )); + } + crate::secret_files::validate_private_file_acl(&fd) + .map_err(|e| format!("keys file {}: {e}", path.display()))?; + let file = std::fs::File::from(fd); + let iter = dotenvy::from_read_iter(file); + let mut pairs = Vec::new(); + for item in iter { + // Parser diagnostics include input that may contain a private key. + let (k, v) = + item.map_err(|_| format!("keys file {}: cannot read or parse dotenv", path.display()))?; + pairs.push((k, Zeroizing::new(v))); + } + KeyRing::from_pairs(pairs, namings).map_err(|e| format!("keys file {}: {e}", path.display())) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic, unused_qualifications)] +mod tests { + use super::*; + use crate::keys::tests::{tdir, with_temp_keys}; + use std::io::Write; + + #[test] + #[cfg(target_os = "macos")] + fn runtime_load_rejects_untrusted_acls_without_mutating_read_only_keys() { + use std::os::unix::fs::PermissionsExt as _; + let identity = std::process::Command::new("/usr/bin/id") + .arg("-un") + .output() + .unwrap(); + assert!(identity.status.success()); + let username = String::from_utf8(identity.stdout).unwrap(); + for mode in [0o400, 0o600] { + with_temp_keys( + &format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32)), + |path| { + std::fs::set_permissions(path, std::fs::Permissions::from_mode(mode)).unwrap(); + for grant in ["everyone allow read", "everyone allow write"] { + assert!( + std::process::Command::new("/bin/chmod") + .args(["+a", grant]) + .arg(path) + .status() + .unwrap() + .success() + ); + for _ in 0..2 { + assert!( + KeyRing::load(path, &[KeyNaming::Env]) + .unwrap_err() + .contains("ACL") + ); + } + let config = path.with_extension("json"); + std::fs::write( + &config, + serde_json::json!({ + "mode": "env", "keys": [{"file": path}], + "env_files": [path.parent().unwrap().join(".env")] + }) + .to_string(), + ) + .unwrap(); + assert!( + crate::keys::provisioning::setup(&config, true, true, false, None) + .unwrap_err() + .contains("ACL") + ); + assert_eq!( + std::fs::metadata(path).unwrap().permissions().mode() & 0o777, + mode + ); + assert!( + std::process::Command::new("/bin/chmod") + .arg("-N") + .arg(path) + .status() + .unwrap() + .success() + ); + } + let trusted = format!("user:{} allow read,write", username.trim()); + assert!( + std::process::Command::new("/bin/chmod") + .args(["+a", &trusted]) + .arg(path) + .status() + .unwrap() + .success() + ); + KeyRing::load(path, &[KeyNaming::Env]).unwrap(); + }, + ); + } + } + + #[test] + fn load_rejects_bad_hex() { + let content = "DOTENV_PRIVATE_KEY=not-hex\n"; + with_temp_keys(content, |p| match KeyRing::load(p, &[KeyNaming::Env]) { + Err(e) if e.contains("not valid hex") => {} + other => panic!("expected bad hex error, got {other:?}"), + }); + } + + #[test] + fn load_redacts_malformed_private_key_assignments() { + let key = "11".repeat(32); + for value in [format!("\"{key}"), format!("\"{key}\" trailing")] { + with_temp_keys(&format!("DOTENV_PRIVATE_KEY={value}\n"), |p| { + let error = KeyRing::load(p, &[KeyNaming::Env]).unwrap_err(); + assert!( + !error.contains(&key), + "parser error must not expose the key" + ); + assert!(error.contains(p.to_str().unwrap())); + assert!(error.contains("cannot read or parse dotenv")); + }); + } + } + + #[test] + fn load_rejects_directory_keys_file() { + // Mode carries no S_IFMT bits, so a directory would pass the permission mask — + // reject by file type. + let dir = tdir("dir-as-keys"); + match KeyRing::load(&dir, &[KeyNaming::Env]) { + Err(e) if e.contains("not a regular file") => {} + other => panic!("expected not-a-regular-file error, got {other:?}"), + } + } + + #[test] + fn load_rejects_world_readable_keys_file() { + use std::os::unix::fs::PermissionsExt; + let dir = crate::test_util::temp_dir::TestDir::new("load"); + let path = dir.join("fixture"); + { + let mut f = std::fs::File::create(&path).unwrap(); + writeln!(f, "DOTENV_PRIVATE_KEY={}", "11".repeat(32)).unwrap(); + } + // 0644: world-readable — must be rejected. + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap(); + match KeyRing::load(&path, &[KeyNaming::Env]) { + Err(e) if e.contains("group/world accessible") => {} + other => panic!("expected group/world permission error, got {other:?}"), + } + let _ = std::fs::remove_file(&path); + } + + #[test] + fn load_rejects_group_readable_keys_file() { + use std::os::unix::fs::PermissionsExt; + let dir = crate::test_util::temp_dir::TestDir::new("load"); + let path = dir.join("fixture"); + { + let mut f = std::fs::File::create(&path).unwrap(); + writeln!(f, "DOTENV_PRIVATE_KEY={}", "11".repeat(32)).unwrap(); + } + // 0640: group-readable — must be rejected. + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o640)).unwrap(); + match KeyRing::load(&path, &[KeyNaming::Env]) { + Err(e) if e.contains("group/world accessible") => {} + other => panic!("expected group permission error, got {other:?}"), + } + let _ = std::fs::remove_file(&path); + } + + #[test] + fn load_rejects_symlink_keys_file() { + let dir = tdir("symlink-keys"); + let real = dir.join("real-keys"); + std::fs::write(&real, format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32))).unwrap(); + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(&real, std::fs::Permissions::from_mode(0o600)).unwrap(); + let link = dir.join(".env.keys"); + std::os::unix::fs::symlink(&real, &link).unwrap(); + match KeyRing::load(&link, &[KeyNaming::Env]) { + Err(e) if e.contains("symlink") => {} + other => panic!("expected symlink rejection error, got {other:?}"), + } + } + + #[test] + fn load_accepts_0600_keys_file() { + // Sanity: a properly locked-down keys file (0600, owned by euid) + // loads normally. This guards against false positives from the + // permission and ownership checks. + let content = format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32)); + with_temp_keys(&content, |p| { + KeyRing::load(p, &[KeyNaming::Env]).expect("0600 keys file owned by euid should load"); + }); + } + + #[test] + fn load_accepts_0400_keys_file() { + use std::os::unix::fs::PermissionsExt; + let dir = crate::test_util::temp_dir::TestDir::new("load"); + let path = dir.join("fixture"); + { + let mut f = std::fs::File::create(&path).unwrap(); + writeln!(f, "DOTENV_PRIVATE_KEY={}", "11".repeat(32)).unwrap(); + } + // 0400: read-only by owner — stricter than 0600, must pass. + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o400)).unwrap(); + KeyRing::load(&path, &[KeyNaming::Env]).expect("0400 keys file owned by euid should load"); + let _ = std::fs::remove_file(&path); + } +} diff --git a/src/keys/mod.rs b/src/keys/mod.rs new file mode 100644 index 0000000..015239c --- /dev/null +++ b/src/keys/mod.rs @@ -0,0 +1,817 @@ +//! Key loading, variable name resolution, and ciphertext decryption. +//! +//! The key ring and resolved values use zeroizing buffers. Decryption tries +//! rotation candidates in order; the source environment is not zeroized. +//! Plaintext values (from `dotenvx set --plain`) are passed through. +//! +//! The `KeyNaming` enum in `adapter/mod.rs` defines the dotenv and bundle +//! namespaces used by loading and resolution. + +use std::collections::HashMap; +use std::path::{Path, PathBuf}; + +use base64::Engine; +use base64::engine::general_purpose::STANDARD as BASE64; +use zeroize::{Zeroize, Zeroizing}; + +use crate::adapter::KeyNaming; +use crate::config::Entry; + +mod dotenv; +mod env; +#[cfg(target_os = "macos")] +mod keychain; +mod load; +pub mod provisioning; +pub mod source; +mod verify; + +/// Shared external-helper verification. +pub use verify::verify_external_binary; + +/// Key-variable predicates shared by loading, setup and launch validation. +pub(crate) use env::{is_key_var_name, is_private_key_var_name}; + +/// Full variable name (adapter-specific, e.g. `DOTENV_PRIVATE_KEY[_]`) +/// → candidate secret keys. Multiple candidates per name come from +/// comma-separated rotation convention; decryption tries each in order. +pub struct KeyRing(HashMap>>); + +// Zeroizing forwards Debug to its inner value; derive would expose every private key. +impl std::fmt::Debug for KeyRing { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("KeyRing") + .field("vars", &self.0.keys().collect::>()) + .finish() + } +} + +impl KeyRing { + /// Look up candidate keys for a given key variable name. + /// Returns `None` if the variable has no candidates in the ring. + pub fn candidates(&self, var: &str) -> Option<&[Zeroizing<[u8; 32]>]> { + self.0.get(var).map(|v| v.as_slice()) + } + + /// Load a `.env.keys` file from `path` and build a key ring. + /// + /// Checks apply to the opened inode, so path replacement cannot change + /// which file is validated and read: + /// - `O_NOFOLLOW`: reject a symlink at `path` (defense-in-depth; also + /// closes the credential-source symlink attack leg). + /// - `mode & 0o077 == 0`: no group or world read/write/exec. A keys + /// file accidentally `chmod 0644` would expose private keys to every + /// process on the host; fail closed instead. + /// - `st_uid == euid`: the file must be owned by the service user. + /// - macOS ACLs: reject read or mutation grants to principals other + /// than root or the effective user without changing the source ACL. + /// + /// `namings` is the required adapter set; entries under other + /// prefixes are dropped (and zeroized) at parse time. + pub fn load(path: &Path, namings: &[KeyNaming]) -> Result { + load::load(path, namings) + } + + /// Parse key values shared by all local key sources. + /// + /// Keep names matching the required adapters' exact prefix or a prefix + /// followed by `_`. Split comma-separated rotation + /// candidates and decode each into a zeroizing 32-byte key. + /// `namings` comes from `ExecConfig::required_namings`; other namespaces + /// are discarded. Input values use `Zeroizing` so discarded + /// material is wiped on drop. + /// + /// # Errors + /// + /// Return an error for invalid key material or an empty required ring. + pub fn from_pairs( + pairs: impl IntoIterator)>, + namings: &[KeyNaming], + ) -> Result { + let mut map: HashMap>> = HashMap::new(); + for (name, mut value) in pairs { + if !namings + .iter() + .any(|n| is_key_var_name(n.key_prefix(), &name)) + { + value.zeroize(); + continue; + } + let mut keys = Vec::new(); + for part in value.split(',') { + let part = part.trim(); + if part.is_empty() { + continue; + } + let mut raw = + hex::decode(part).map_err(|_| format!("{name}: entry is not valid hex"))?; + if raw.len() != 32 { + raw.zeroize(); + return Err(format!("{name}: expected a 32-byte key")); + } + let mut arr = [0_u8; 32]; + arr.copy_from_slice(&raw); + raw.zeroize(); + keys.push(Zeroizing::new(arr)); + } + value.zeroize(); + if keys.is_empty() { + return Err(format!("{name}: no usable keys")); + } + map.insert(name, keys); + } + if map.is_empty() { + return Err(empty_error(namings)); + } + Ok(KeyRing(map)) + } + + /// Read private-key variables matching the required adapter namespaces + /// from the process environment. + pub fn from_env(namings: &[KeyNaming]) -> Result { + env::from_env(namings) + } + + /// Read macOS Keychain through the default search list. Each variable uses + /// one generic-password item: + /// service = `service`, account = the adapter's key variable name. + /// Only the vars actually needed (derived from artifact names) are + /// fetched. + #[cfg(target_os = "macos")] + pub fn from_keychain( + service: &str, + vars: &[String], + namings: &[KeyNaming], + ) -> Result { + keychain::from_keychain(service, vars, namings) + } +} + +/// Human-readable empty-ring error for a naming set: a single naming +/// keeps its adapter-specific message; multiple namings join them. +fn empty_error(namings: &[KeyNaming]) -> String { + match namings { + [] => "no key material admitted (empty naming set)".to_string(), + [single] => single.empty_error(), + many => format!( + "no {}", + many.iter() + .map(|n| n.empty_error().trim_start_matches("no ").to_string()) + .collect::>() + .join(" or ") + ), + } +} + +/// Check an ASCII identifier used for environment names and secret filenames. +pub fn is_ident(k: &str) -> bool { + let mut cs = k.chars(); + matches!(cs.next(), Some(c) if c.is_ascii_alphabetic() || c == '_') + && cs.all(|c| c.is_ascii_alphanumeric() || c == '_') +} + +/// Decrypt one raw value: `encrypted:` via the ring (rotation-aware), +/// anything else passed through as opaque bytes (plaintext passthrough). +/// Base64 payload may contain ASCII whitespace (spaces, newlines, tabs, CR), +/// matching the lenient decoding for line-wrapped values. +pub fn decrypt_value( + env_file: &Path, + key: &str, + raw: &str, + ring: &KeyRing, + naming: KeyNaming, +) -> Result>, String> { + let Some(b64) = raw.strip_prefix("encrypted:") else { + return Ok(Zeroizing::new(raw.as_bytes().to_vec())); + }; + let ciphertext: Zeroizing> = { + if b64.chars().any(|c| c.is_ascii_whitespace()) { + // Zeroizing: b64_clean holds derived ciphertext material (base64 + // of the encrypted blob). Zeroize on drop for defense-in-depth, + // matching the crate's hygiene posture on key and plaintext buffers. + let b64_clean = Zeroizing::new( + b64.chars() + .filter(|c| !c.is_ascii_whitespace()) + .collect::(), + ); + Zeroizing::new( + BASE64 + .decode(&*b64_clean) + .map_err(|_| format!("{}: {key} is not valid base64", env_file.display()))?, + ) + } else { + Zeroizing::new( + BASE64 + .decode(b64) + .map_err(|_| format!("{}: {key} is not valid base64", env_file.display()))?, + ) + } + }; + let var = naming.key_var_for(env_file)?; + let candidates = ring + .0 + .get(&var) + .ok_or_else(|| format!("key ring has no {var} entry"))?; + for sk in candidates { + if let Ok(pt) = ecies::decrypt(&sk[..], &ciphertext) { + return Ok(Zeroizing::new(pt)); + } + } + // No candidate count in the error text — the rotation-set size is not something + // errors should leak. + Err(format!( + "{}: no key under {var} decrypts {key}", + env_file.display() + )) +} + +/// Resolve a single entry using the key ring. +/// Supports both encrypted values and plaintext passthrough. +pub fn resolve( + entry: &Entry, + ring: &KeyRing, + naming: KeyNaming, +) -> Result>, String> { + let mut budget = dotenv::Budget::default(); + let iter = dotenv::read(&entry.env_file, &mut budget, Some(&entry.env_file_sha256))?; + // Last assignment wins, matching dotenv semantics within one file. + let mut found: Option> = None; + for item in iter { + let (k, v) = item; + if k == entry.key { + found = Some(v); + } + } + let raw = + found.ok_or_else(|| format!("{}: no key named {}", entry.env_file.display(), entry.key))?; + + decrypt_value(&entry.env_file, &entry.key, &raw, ring, naming) +} + +/// Resolved (name, secret-bytes) pairs, in injection order. +pub type ResolvedVars = Vec<(String, Zeroizing>)>; + +/// Outcome of a [`resolve_all`] pass. +pub struct Resolution { + /// Resolved (name, plaintext) pairs in injection order. + pub resolved: ResolvedVars, + /// `(name, error)` for each encrypted value that could not be + /// decrypted and was skipped under `strict: false`. Recorded so + /// `--verify-keys` can fail closed on a partial key rotation. + /// Always empty under `strict: true`, where + /// the first failure aborts the whole pass instead. + pub failed: Vec<(String, String)>, +} + +// A derived Debug implementation would expose decrypted values; print names only. +impl std::fmt::Debug for Resolution { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Resolution") + .field( + "resolved", + &self.resolved.iter().map(|(k, _)| k).collect::>(), + ) + .field( + "failed", + &self.failed.iter().map(|(k, _)| k).collect::>(), + ) + .finish() + } +} + +/// Resolve every key across `files` per the precedence contract +/// (see `docs/src/reference/launcher-contract.md`): within one file the last +/// assignment wins; across files the first file defining a key wins +/// unless `overload`; keys already present in the process environment are +/// skipped unless `overload`. Adapter metadata keys are dropped; +/// non-identifier keys are a hard error (they become env names/filenames). +/// Undecryptable values abort under `strict`; otherwise they are skipped +/// and recorded in [`Resolution::failed`]. +pub fn resolve_all( + files: &[PathBuf], + ring: &KeyRing, + overload: bool, + strict: bool, + env_has: &dyn Fn(&str) -> bool, + naming: KeyNaming, +) -> Result { + let metadata_prefix = naming.metadata_prefix(); + let mut order: Vec = Vec::new(); + let mut merged: HashMap)> = HashMap::new(); + let mut budget = dotenv::Budget::default(); + for f in files { + let iter = dotenv::read(f, &mut budget, None)?; + let mut file_vals: HashMap> = HashMap::new(); + let mut file_order: Vec = Vec::new(); + for item in iter { + let (k, v) = item; + if let Some(prefix) = metadata_prefix + && k.starts_with(prefix) + { + continue; + } + if !is_ident(&k) { + return Err(format!( + "{}: refusing non-identifier key {k:?}", + f.display() + )); + } + if !file_vals.contains_key(&k) { + file_order.push(k.clone()); + } + file_vals.insert(k, v); // last assignment within a file wins + } + for k in file_order { + // Unreachable invariant (file_order mirrors file_vals), but a clear error + // beats an abort under panic=abort. + let Some(v) = file_vals.remove(&k) else { + return Err(format!("internal: {k} in file_order but not file_vals")); + }; + if let Some(slot) = merged.get_mut(&k) { + if overload { + *slot = (f.clone(), v); // later file wins under overload + } + } else { + order.push(k.clone()); + merged.insert(k, (f.clone(), v)); + } + } + } + let mut out = Vec::new(); + let mut failed = Vec::new(); + for k in order { + if !overload && env_has(&k) { + continue; // process environment wins + } + // Unreachable invariant (order mirrors merged), but a clear error beats an + // abort under panic=abort. + let Some((file, raw)) = merged.remove(&k) else { + return Err(format!("internal: {k} in order but not merged")); + }; + match decrypt_value(&file, &k, &raw, ring, naming) { + Ok(v) => out.push((k, v)), + Err(e) if strict => return Err(e), + Err(e) => { + crate::server::log(&format!("non-strict: skipping {k}: {e}")); + failed.push((k, e)); + } + } + } + Ok(Resolution { + resolved: out, + failed, + }) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic, unused_qualifications)] +/// Inline unit tests for key loading, resolution, and decryption. +pub mod tests { + use super::*; + use crate::adapter::KeyNaming; + + /// Test secret key hex — never use outside tests. + pub const TEST_SK_HEX: &str = + "1111111111111111111111111111111111111111111111111111111111111111"; + + /// Build a test key ring with the test secret key under + /// `POSTMASTER_KEY` (for bundle adapter tests). + pub fn make_test_ring() -> KeyRing { + let pairs = vec![( + "POSTMASTER_KEY".to_string(), + Zeroizing::new(TEST_SK_HEX.to_string()), + )]; + KeyRing::from_pairs(pairs, &[KeyNaming::Bundle]).unwrap() + } + use std::io::Write; + use std::path::Path; + + /// Shared with the `load` submodule's tests. + pub fn with_temp_keys(content: &str, f: impl FnOnce(&Path)) { + use std::os::unix::fs::PermissionsExt; + let dir = crate::test_util::temp_dir::TestDir::new("mod"); + let path = dir.join("fixture"); + { + let mut f = std::fs::File::create(&path).unwrap(); + writeln!(f, "{}", content).unwrap(); + } + // Match the owner-only permissions required by KeyRing::load. + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap(); + f(&path); + let _ = std::fs::remove_file(&path); + } + + /// Shared with the `load` submodule's tests. + pub fn tdir(tag: &str) -> crate::test_util::temp_dir::TestDir { + crate::test_util::temp_dir::TestDir::new(tag) + } + + #[test] + fn malformed_dotenv_diagnostics_do_not_contain_values() { + use sha2::Digest as _; + let dir = tdir("redaction"); + let path = dir.join(".env"); + let ring = KeyRing(HashMap::new()); + for value in [ + "\"PRIVATE_SENTINEL", + "\"PRIVATE_SENTINEL\" trailing", + "\"PRIVATE_SENTINEL\\q\"", + "\"PRIVATE_SENTINEL\nsecond", + ] { + std::fs::write(&path, format!("SECRET={value}\n")).unwrap(); + let entry = Entry { + env_file: path.clone(), + key: "SECRET".into(), + env_file_sha256: vec![sha2::Sha256::digest(std::fs::read(&path).unwrap()).into()], + peer_user: None, + }; + let error = resolve(&entry, &ring, KeyNaming::Env).unwrap_err(); + assert!(!error.contains("PRIVATE_SENTINEL")); + assert!(error.contains(path.to_str().unwrap())); + for strict in [false, true] { + let error = resolve_all( + std::slice::from_ref(&path), + &ring, + false, + strict, + &|_| false, + KeyNaming::Env, + ) + .unwrap_err(); + assert!(!error.contains("PRIVATE_SENTINEL")); + assert!(error.contains(path.to_str().unwrap())); + } + } + } + + #[test] + fn daemon_authorizes_source_before_interpolation_or_decryption() { + use sha2::Digest as _; + let dir = tdir("authorized"); + let path = dir.join(".env"); + let (sk, pk) = ecies::utils::generate_keypair(); + let ring = KeyRing::from_pairs( + [( + "DOTENV_PRIVATE_KEY".into(), + Zeroizing::new(format!( + "{},{}", + "11".repeat(32), + hex::encode(sk.serialize()) + )), + )], + &[KeyNaming::Env], + ) + .unwrap(); + let allowed = ecies::encrypt(&pk.serialize(), b"allowed").unwrap(); + let foreign = ecies::encrypt(&pk.serialize(), b"foreign").unwrap(); + let encoded = BASE64.encode(&allowed); + let wrapped = encoded + .as_bytes() + .chunks(7) + .map(|c| std::str::from_utf8(c).unwrap()) + .collect::>() + .join(" \n"); + std::fs::write( + &path, + format!("SECRET=discarded\nSOURCE='encrypted:{wrapped}'\nSECRET=${{SOURCE}}\n"), + ) + .unwrap(); + let mut entry = Entry { + env_file: path.clone(), + key: "SECRET".into(), + env_file_sha256: vec![sha2::Sha256::digest(std::fs::read(&path).unwrap()).into()], + peer_user: None, + }; + assert_eq!( + &*resolve(&entry, &ring, KeyNaming::Env).unwrap(), + b"allowed" + ); + // Both authentic foreign ciphertext and plaintext substitutions are unauthorized. + for raw in [ + format!("SECRET='encrypted:{}'\n", BASE64.encode(&foreign)), + "SECRET=${PATH}\n".into(), + "SECRET=chosen\n".into(), + ] { + std::fs::write(&path, raw).unwrap(); + assert!( + resolve(&entry, &ring, KeyNaming::Env) + .unwrap_err() + .contains("not authorized") + ); + } + entry + .env_file_sha256 + .push(sha2::Sha256::digest(std::fs::read(&path).unwrap()).into()); + assert_eq!(&*resolve(&entry, &ring, KeyNaming::Env).unwrap(), b"chosen"); + entry.env_file_sha256.clear(); + assert!( + resolve(&entry, &ring, KeyNaming::Env) + .unwrap_err() + .contains("not authorized") + ); + } + + #[test] + fn resolve_plaintext_passthrough_with_empty_ring() { + use sha2::Digest as _; + // Create a real .env file with a plaintext value (simulating --plain) + let env_dir = crate::test_util::temp_dir::TestDir::new("mod"); + let env_path = env_dir.join("fixture"); + { + let mut f = std::fs::File::create(&env_path).unwrap(); + writeln!(f, "PLAIN=hello-world").unwrap(); + } + + let entry = Entry { + env_file: env_path.clone(), + key: "PLAIN".to_string(), + env_file_sha256: vec![sha2::Sha256::digest(std::fs::read(&env_path).unwrap()).into()], + peer_user: None, + }; + // Ring can be empty for plaintext path + let ring = KeyRing(HashMap::new()); + let result = resolve(&entry, &ring, KeyNaming::Env).unwrap(); + assert_eq!(&*result, b"hello-world"); + + let _ = std::fs::remove_file(&env_path); + } + + #[test] + fn from_pairs_filters_and_rotates() { + let ring = KeyRing::from_pairs( + [ + ("UNRELATED".to_string(), Zeroizing::new("x".to_string())), + ( + "DOTENV_PRIVATE_KEY_PRODUCTION".to_string(), + Zeroizing::new(format!("{},{}", "22".repeat(32), "33".repeat(32))), + ), + ], + &[KeyNaming::Env], + ) + .unwrap(); + assert_eq!(ring.0.len(), 1); + assert_eq!(ring.0["DOTENV_PRIVATE_KEY_PRODUCTION"].len(), 2); + } + + #[test] + fn from_pairs_admits_exactly_the_required_namings() { + // The bundle-ring gap fix: a config requiring both adapters must + // get both prefix families in the ring, and nothing else. + let pairs = || { + [ + ( + "DOTENV_PRIVATE_KEY".to_string(), + Zeroizing::new("22".repeat(32)), + ), + ( + "POSTMASTER_KEY".to_string(), + Zeroizing::new("33".repeat(32)), + ), + ("UNRELATED".to_string(), Zeroizing::new("44".repeat(32))), + ] + }; + + let both = KeyRing::from_pairs(pairs(), &[KeyNaming::Env, KeyNaming::Bundle]).unwrap(); + assert!(both.candidates("DOTENV_PRIVATE_KEY").is_some()); + assert!(both.candidates("POSTMASTER_KEY").is_some()); + assert_eq!(both.0.len(), 2, "UNRELATED must be dropped"); + + // Least privilege: a naming the config does not require is NOT + // admitted, even when the source provides it. + let env_only = KeyRing::from_pairs(pairs(), &[KeyNaming::Env]).unwrap(); + assert!(env_only.candidates("DOTENV_PRIVATE_KEY").is_some()); + assert!(env_only.candidates("POSTMASTER_KEY").is_none()); + + // A bundle-only requirement with only Env material present fails + // closed with the adapter's own empty message. + let err = KeyRing::from_pairs( + [( + "DOTENV_PRIVATE_KEY".to_string(), + Zeroizing::new("22".repeat(32)), + )], + &[KeyNaming::Bundle], + ) + .unwrap_err(); + assert_eq!(err, KeyNaming::Bundle.empty_error()); + } + + #[test] + fn from_pairs_empty_is_error() { + assert!( + KeyRing::from_pairs( + [("A".to_string(), Zeroizing::new("b".to_string()))], + &[KeyNaming::Env] + ) + .is_err() + ); + } + + #[test] + fn is_ident_rules() { + assert!(is_ident("DATABASE_URL") && is_ident("_x9")); + assert!(!is_ident("9x") && !is_ident("a-b") && !is_ident("") && !is_ident("a b")); + } + + #[test] + fn resolve_all_precedence() { + let d = tdir("prec"); + std::fs::write( + d.join(".env"), + "A=first\nB=one\nB=two\nDOTENV_PUBLIC_KEY=zz\n", + ) + .unwrap(); + std::fs::write(d.join(".env.local"), "A=second\nC=three\n").unwrap(); + let files = [d.join(".env"), d.join(".env.local")]; + let ring = KeyRing(HashMap::new()); + + // default: first file wins; within a file last assignment wins; + // process-env presence suppresses; DOTENV_* filtered. + let out = resolve_all(&files, &ring, false, true, &|k| k == "C", KeyNaming::Env).unwrap(); + let got: Vec<(&str, &[u8])> = out + .resolved + .iter() + .map(|(k, v)| (k.as_str(), &v[..])) + .collect(); + assert_eq!( + got, + vec![("A", b"first".as_slice()), ("B", b"two".as_slice())] + ); + + // overload: later file wins, env presence ignored. + let out = resolve_all(&files, &ring, true, true, &|k| k == "C", KeyNaming::Env).unwrap(); + let got: Vec<(&str, &[u8])> = out + .resolved + .iter() + .map(|(k, v)| (k.as_str(), &v[..])) + .collect(); + assert_eq!( + got, + vec![ + ("A", b"second".as_slice()), + ("B", b"two".as_slice()), + ("C", b"three".as_slice()) + ] + ); + } + + #[test] + fn resolve_all_rejects_non_identifier() { + // dotenvy rejects keys starting with `-` or digit during parsing, but accepts `.` + // in subsequent characters (e.g., BAD.KEY=x parses fine). Our is_ident check rejects + // `.` in all positions, so a dotted key exercises the rejection branch in resolve_all. + let d = tdir("ident"); + std::fs::write(d.join(".env"), "BAD.KEY=x\n").unwrap(); + let ring = KeyRing(HashMap::new()); + let e = resolve_all( + &[d.join(".env")], + &ring, + false, + true, + &|_| false, + KeyNaming::Env, + ) + .unwrap_err(); + assert!(e.contains("non-identifier"), "{e}"); + } + + #[test] + fn resolve_all_strict_fails_on_undecryptable() { + let d = tdir("strict"); + std::fs::write(d.join(".env"), "A=encrypted:!!!notbase64\n").unwrap(); + let ring = KeyRing(HashMap::new()); + assert!( + resolve_all( + &[d.join(".env")], + &ring, + false, + true, + &|_| false, + KeyNaming::Env + ) + .is_err() + ); + // Non-strict: skipped, not served wrong — and the skip is recorded so + // --verify-keys can fail closed on it. + let out = resolve_all( + &[d.join(".env")], + &ring, + false, + false, + &|_| false, + KeyNaming::Env, + ) + .unwrap(); + assert!(out.resolved.is_empty()); + assert_eq!(out.failed.len(), 1); + assert_eq!(out.failed[0].0, "A"); + } + + #[test] + fn keyring_debug_redacts_key_material() { + // A derived Debug would print every 32-byte key verbatim (Zeroizing's Debug + // passes through to the inner value). Names only. + let ring = KeyRing::from_pairs( + [( + "DOTENV_PRIVATE_KEY".to_string(), + Zeroizing::new("11".repeat(32)), + )], + &[KeyNaming::Env], + ) + .unwrap(); + let dbg = format!("{ring:?}"); + assert!(dbg.contains("DOTENV_PRIVATE_KEY")); + assert!( + !dbg.contains("17, 17"), + "debug output must not contain raw key bytes: {dbg}" + ); + } + + #[test] + fn resolution_debug_redacts_plaintext() { + // Debug output must expose names without decrypted values. + let r = Resolution { + resolved: vec![( + "MY_SECRET".to_string(), + Zeroizing::new(b"super-secret-plaintext".to_vec()), + )], + failed: vec![("OTHER".to_string(), "decrypt failed".to_string())], + }; + let dbg = format!("{r:?}"); + assert!(dbg.contains("MY_SECRET")); + assert!(dbg.contains("OTHER")); + assert!( + !dbg.contains("super-secret"), + "debug output must not contain plaintext: {dbg}" + ); + } + + #[test] + fn from_pairs_uses_the_exact_key_var_predicate() { + // Reject prefix lookalikes consistently across file and environment sources. + let ring = KeyRing::from_pairs( + [ + ( + "DOTENV_PRIVATE_KEYFOO".to_string(), + Zeroizing::new("22".repeat(32)), + ), + ( + "DOTENV_PRIVATE_KEY".to_string(), + Zeroizing::new("33".repeat(32)), + ), + ], + &[KeyNaming::Env], + ) + .unwrap(); + assert!(ring.candidates("DOTENV_PRIVATE_KEY").is_some()); + assert!(ring.candidates("DOTENV_PRIVATE_KEYFOO").is_none()); + } + + #[test] + fn resolve_all_refuses_symlinked_env_file() { + // A symlink at a configured .env path must fail before reading its target. + let d = tdir("symlink"); + std::fs::write(d.join(".env.real"), "A=plain\n").unwrap(); + std::os::unix::fs::symlink(d.join(".env.real"), d.join(".env")).unwrap(); + let ring = KeyRing(HashMap::new()); + let err = resolve_all( + &[d.join(".env")], + &ring, + false, + true, + &|_| false, + KeyNaming::Env, + ) + .unwrap_err(); + assert!(err.contains("symlink"), "{err}"); + } + + #[test] + fn decrypt_value_fails_closed_on_bad_base64_and_missing_ring_entry() { + // decrypt_value's two fail-closed legs, exercised directly (the resolve paths + // reach them only indirectly). + let env_file = Path::new(".env"); + let ring = KeyRing(HashMap::new()); + + // Malformed base64 after the encrypted: prefix → parse error + // naming the file and key, never a decrypt attempt. + let err = decrypt_value( + env_file, + "KEY", + "encrypted:!!!not-base64", + &ring, + KeyNaming::Env, + ) + .unwrap_err(); + assert!(err.contains("KEY is not valid base64"), "{err}"); + + // Well-formed base64 but the ring lacks the file's mapped key + // variable → missing-entry error. + let b64 = BASE64.encode(b"well-formed"); + let raw = format!("encrypted:{b64}"); + let err = decrypt_value(env_file, "KEY", &raw, &ring, KeyNaming::Env).unwrap_err(); + assert!( + err.contains("key ring has no DOTENV_PRIVATE_KEY entry"), + "{err}" + ); + } +} diff --git a/src/keys/provisioning/cleanup.rs b/src/keys/provisioning/cleanup.rs new file mode 100644 index 0000000..a16ad1f --- /dev/null +++ b/src/keys/provisioning/cleanup.rs @@ -0,0 +1,275 @@ +//! `postmaster cleanup` command path. + +use std::os::fd::AsFd; +use std::path::Path; + +use crate::secret_files::{MANAGED_SENTINEL, open_secrets_dir, read_dir_names}; +use crate::server::log; + +/// `postmaster cleanup`: remove all secret files from the secrets_dir +/// configured in the exec config. Intended for `ExecStopPost` in systemd +/// or equivalent lifecycle hooks. Removes regular files without decrypting. +/// Bulk removal is guarded by the +/// `.postmaster-managed` sentinel: a non-empty directory lacking it is +/// refused (postmaster only bulk-deletes directories it manages). The +/// sentinel is removed last, and only when every managed regular file +/// was removed successfully — on any stat/unlink failure the sentinel +/// is retained and the command fails, so a retry is not refused as +/// unmanaged while plaintext files survive. Safe to run even if the +/// directory is empty or does not exist. +pub fn cleanup(config_path: &Path) -> Result<(), String> { + let cfg = crate::launcher::parse_exec_config(config_path)?; + let dir = cfg + .secrets_dir + .as_deref() + .ok_or("cleanup: config has no secrets_dir — nothing to clean up")?; + // Pin the directory by fd: O_DIRECTORY|O_NOFOLLOW rejects a symlinked or + // non-directory secrets dir at open, and the sentinel check, the per-entry stat, + // and every unlink below are all relative to the pinned inode — no path is ever + // re-resolved. + let dir_fd = match open_secrets_dir(dir) { + Ok(fd) => fd, + Err(rustix::io::Errno::NOENT) => { + log(&format!( + "cleanup: {} does not exist; nothing to clean up", + dir.display() + )); + return Ok(()); + } + Err(e @ (rustix::io::Errno::LOOP | rustix::io::Errno::NOTDIR)) => { + return Err(format!( + "{}: cleanup: refusing a symlinked or non-directory secrets dir ({e})", + dir.display() + )); + } + Err(e) => return Err(format!("{}: cleanup: {e}", dir.display())), + }; + let names = read_dir_names(&dir_fd).map_err(|e| format!("{}: cleanup: {e}", dir.display()))?; + if names.is_empty() { + log(&format!( + "cleanup: {} is empty; nothing to clean up", + dir.display() + )); + return Ok(()); + } + // Managed-dir guard: non-empty and no sentinel means postmaster never wrote here — + // bulk deletes could hit foreign files. Refuse. + match rustix::fs::statat( + &dir_fd, + MANAGED_SENTINEL, + rustix::fs::AtFlags::SYMLINK_NOFOLLOW, + ) { + Ok(stat) if rustix::fs::FileType::from_raw_mode(stat.st_mode).is_file() => {} + _ => { + return Err(format!( + "{}: cleanup: no {MANAGED_SENTINEL} sentinel; refusing to bulk-delete in a directory postmaster did not write to", + dir.display() + )); + } + } + let mut removed = 0_usize; + let mut had_failure = false; + for name in &names { + // The sentinel is infrastructure, not a secret — skipped here + // and removed last, so an interrupted cleanup can be re-run. + if name.to_str() == Some(MANAGED_SENTINEL) { + continue; + } + let path = dir.join(name); + match rustix::fs::statat(&dir_fd, name, rustix::fs::AtFlags::SYMLINK_NOFOLLOW) { + Ok(stat) if rustix::fs::FileType::from_raw_mode(stat.st_mode).is_file() => { + match rustix::fs::unlinkat(&dir_fd, name, rustix::fs::AtFlags::empty()) { + Ok(()) => removed += 1, + Err(e) => { + had_failure = true; + log(&format!("{}: cleanup: {e}", path.display())); + } + } + } + Ok(stat) => { + // Subdirectories and symlinks are skipped, not failures. + log(&format!( + "{}: cleanup: skipping non-file (type {:?})", + path.display(), + rustix::fs::FileType::from_raw_mode(stat.st_mode) + )); + } + Err(e) => { + had_failure = true; + log(&format!("{}: cleanup: stat: {e}", path.display())); + } + } + } + finish_cleanup(&dir_fd, dir, removed, had_failure) +} + +/// Sentinel disposition after the removal pass. The sentinel is removed +/// last (so an interrupted cleanup can be re-run), and ONLY when every +/// managed regular file came out: on any stat/unlink failure it is +/// retained and the command fails — removing it would make the next +/// retry refuse the directory as unmanaged and strand the surviving +/// plaintext files. +fn finish_cleanup( + dir_fd: impl AsFd, + dir: &Path, + removed: usize, + had_failure: bool, +) -> Result<(), String> { + if had_failure { + return Err(format!( + "{}: cleanup: not all files could be removed; retaining the {MANAGED_SENTINEL} sentinel so a retry is not refused as unmanaged", + dir.display() + )); + } + // Remove the sentinel last (see above); best-effort — with every + // secret gone, a surviving sentinel is harmless. + match rustix::fs::unlinkat(dir_fd, MANAGED_SENTINEL, rustix::fs::AtFlags::empty()) { + Ok(()) | Err(rustix::io::Errno::NOENT) => {} + Err(e) => log(&format!( + "{}: cleanup: {e}", + dir.join(MANAGED_SENTINEL).display() + )), + } + log(&format!( + "cleanup: removed {removed} file(s) from {}", + dir.display() + )); + Ok(()) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic)] +mod tests { + use super::*; + use std::fs; + + #[test] + fn cleanup_removes_all_files_from_secrets_dir() { + let dir = crate::test_util::temp_dir::TestDir::new("cleanup"); + // Cleanup requires a postmaster-managed (owner-only) dir; match real + // deployments. + use std::os::unix::fs::PermissionsExt; + fs::set_permissions(&dir, fs::Permissions::from_mode(0o700)).unwrap(); + fs::write(dir.join("KEY_A"), b"secret-a").unwrap(); + fs::write(dir.join("KEY_B"), b"secret-b").unwrap(); + fs::create_dir(dir.join("subdir")).unwrap(); + fs::write(dir.join(MANAGED_SENTINEL), b"").unwrap(); + + let cfg_path = dir.join("exec.json"); + fs::write( + &cfg_path, + format!( + r#"{{"mode":"files","keys":["environment"],"env_files":["/nonexistent"],"secrets_dir":"{}"}}"#, + dir.display() + ), + ) + .unwrap(); + + cleanup(&cfg_path).unwrap(); + + assert!(!dir.join("KEY_A").exists(), "KEY_A should be removed"); + assert!(!dir.join("KEY_B").exists(), "KEY_B should be removed"); + assert!(dir.join("subdir").exists(), "subdir should be preserved"); + assert!( + !dir.join(MANAGED_SENTINEL).exists(), + "sentinel is removed last" + ); + } + + #[test] + fn cleanup_refuses_unmanaged_dir() { + // A non-empty dir without the sentinel was never written by postmaster; cleanup + // must refuse to bulk-delete there (foreign files could be present). + let dir = crate::test_util::temp_dir::TestDir::new("cleanup"); + fs::write(dir.join("FOREIGN"), b"not-ours").unwrap(); + let cfg_path = dir.join("exec.json"); + fs::write( + &cfg_path, + format!( + r#"{{"mode":"files","keys":["environment"],"env_files":["/nonexistent"],"secrets_dir":"{}"}}"#, + dir.display() + ), + ) + .unwrap(); + + let err = cleanup(&cfg_path).unwrap_err(); + + assert!(err.contains("sentinel"), "{err}"); + assert!(dir.join("FOREIGN").exists(), "nothing may be deleted"); + } + + #[test] + fn cleanup_nonexistent_dir_is_ok() { + let dir = crate::test_util::temp_dir::TestDir::new("cleanup"); + let cfg_path = dir.join("exec.json"); + fs::write( + &cfg_path, + format!( + r#"{{"mode":"files","keys":["environment"],"env_files":["/nonexistent"],"secrets_dir":"{}/no-such-dir"}}"#, + dir.display() + ), + ) + .unwrap(); + + assert!(cleanup(&cfg_path).is_ok()); + } + + #[test] + fn cleanup_retains_sentinel_after_a_failed_removal() { + // Root bypasses directory permission checks (CAP_DAC_OVERRIDE), + // so the induced unlink failure below only occurs for non-root. + if rustix::process::geteuid().is_root() { + return; + } + use std::os::unix::fs::PermissionsExt; + let dir = crate::test_util::temp_dir::TestDir::new("cleanup"); + fs::set_permissions(&dir, fs::Permissions::from_mode(0o700)).unwrap(); + fs::write(dir.join("KEY_A"), b"secret-a").unwrap(); + fs::write(dir.join(MANAGED_SENTINEL), b"").unwrap(); + let cfg_path = dir.join("exec.json"); + fs::write( + &cfg_path, + format!( + r#"{{"mode":"files","keys":["environment"],"env_files":["/nonexistent"],"secrets_dir":"{}"}}"#, + dir.display() + ), + ) + .unwrap(); + // Make every unlink inside the dir fail (EACCES): removal needs + // write permission on the containing directory. Enumeration and + // stat still work (r-x), so KEY_A is found and its removal fails. + fs::set_permissions(&dir, fs::Permissions::from_mode(0o500)).unwrap(); + + let err = cleanup(&cfg_path).unwrap_err(); + + // Restore write permission so the temp dir can be cleaned up. + fs::set_permissions(&dir, fs::Permissions::from_mode(0o700)).unwrap(); + assert!(err.contains("retaining"), "{err}"); + assert!( + dir.join(MANAGED_SENTINEL).exists(), + "the sentinel must be retained so a retry is not refused as unmanaged" + ); + assert!( + dir.join("KEY_A").exists(), + "the file whose removal failed must still be there" + ); + } + + #[test] + fn finish_cleanup_removes_sentinel_only_without_failures() { + use std::os::unix::fs::PermissionsExt; + let dir = crate::test_util::temp_dir::TestDir::new("cleanup"); + fs::set_permissions(&dir, fs::Permissions::from_mode(0o700)).unwrap(); + fs::write(dir.join(MANAGED_SENTINEL), b"").unwrap(); + let dir_fd = open_secrets_dir(&dir).unwrap(); + + // Failure leg: the sentinel is retained and the command fails. + let err = finish_cleanup(&dir_fd, &dir, 0, true).unwrap_err(); + assert!(err.contains("retaining"), "{err}"); + assert!(dir.join(MANAGED_SENTINEL).exists()); + + // Clean leg: the sentinel goes and the command succeeds. + finish_cleanup(&dir_fd, &dir, 1, false).unwrap(); + assert!(!dir.join(MANAGED_SENTINEL).exists()); + } +} diff --git a/src/keys/provisioning/input.rs b/src/keys/provisioning/input.rs new file mode 100644 index 0000000..cf7df9d --- /dev/null +++ b/src/keys/provisioning/input.rs @@ -0,0 +1,304 @@ +//! Secret stdin input with terminal echo suppressed and restored before signal delivery. + +use std::io::{BufRead as _, IsTerminal as _, Read as _, Write as _}; + +use rustix::termios::{LocalModes, OptionalActions, Termios, tcgetattr, tcsetattr}; +use zeroize::Zeroizing; + +struct EchoGuard { + terminal: Option, + flags: Option, +} + +impl EchoGuard { + fn restore(&mut self, discard_input: bool) -> Result<(), String> { + let discarded = if discard_input && (self.terminal.is_some() || self.flags.is_some()) { + rustix::termios::tcflush(std::io::stdin(), rustix::termios::QueueSelector::IFlush) + .map_err(|e| format!("cannot discard terminal input: {e}")) + } else { + Ok(()) + }; + let terminal = if let Some(original) = &self.terminal { + tcsetattr(std::io::stdin(), OptionalActions::Now, original) + .map_err(|e| format!("cannot restore terminal settings: {e}")) + } else { + Ok(()) + }; + if terminal.is_ok() { + self.terminal = None; + } + let flags = if let Some(original) = self.flags { + rustix::fs::fcntl_setfl(std::io::stdin(), original) + .map_err(|e| format!("cannot restore stdin flags: {e}")) + } else { + Ok(()) + }; + if flags.is_ok() { + self.flags = None; + } + discarded.and(terminal).and(flags) + } +} + +impl Drop for EchoGuard { + fn drop(&mut self) { + if let Err(e) = self.restore(true) { + crate::server::log(&e); + } + } +} + +/// Read one line or a multiline EOF-terminated value without terminal echo. +/// Redirected input uses stdin's existing buffer. Errors never include input values. +pub(super) fn read_secret(prompt: &str, single_line: bool) -> Result, String> { + let stdin = std::io::stdin(); + let mut value = Zeroizing::new(String::new()); + if !stdin.is_terminal() { + writeln!(std::io::stderr().lock(), "{prompt}") + .map_err(|e| format!("cannot write secret input prompt: {e}"))?; + let mut input = stdin.lock(); + if single_line { + input.read_line(&mut value) + } else { + input.read_to_string(&mut value) + } + .map_err(|_| "cannot read secret input")?; + return Ok(value); + } + // Drop order matters: restore echo before unblocking a pending termination or suspend. + let signals = crate::launcher::TerminationGuard::block_input(); + if !signals.active() { + return Err("cannot protect terminal input from interruption".into()); + } + let original = tcgetattr(&stdin).map_err(|e| format!("cannot read terminal settings: {e}"))?; + let flags = + rustix::fs::fcntl_getfl(&stdin).map_err(|e| format!("cannot read stdin flags: {e}"))?; + let mut no_echo = original.clone(); + no_echo + .local_modes + .remove(LocalModes::ECHO | LocalModes::ECHONL); + if !no_echo.local_modes.contains(LocalModes::ICANON) { + no_echo.special_codes[rustix::termios::SpecialCodeIndex::VMIN] = 1; + no_echo.special_codes[rustix::termios::SpecialCodeIndex::VTIME] = 0; + } + let mut echo = EchoGuard { + terminal: Some(original), + flags: Some(flags), + }; + rustix::fs::fcntl_setfl(&stdin, flags | rustix::fs::OFlags::NONBLOCK) + .map_err(|e| format!("cannot make terminal input nonblocking: {e}"))?; + tcsetattr(&stdin, OptionalActions::Now, &no_echo) + .map_err(|e| format!("cannot suppress terminal echo: {e}"))?; + writeln!(std::io::stderr().lock(), "{prompt}") + .map_err(|e| format!("cannot write secret input prompt: {e}"))?; + let mut input = stdin.lock(); + loop { + if signals.input_pending()? { + return Err("secret input interrupted".into()); + } + // Read buffered data first. NONBLOCK also protects partial noncanonical lines. + match input.read_line(&mut value) { + Ok(0) => break, + Ok(_) if single_line => break, + Ok(_) => continue, + Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue, + Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {} + Err(_) => return Err("cannot read secret input".into()), + } + let mut fds = [rustix::event::PollFd::new( + &stdin, + rustix::event::PollFlags::IN, + )]; + let timeout = rustix::event::Timespec { + tv_sec: 0, + tv_nsec: 100_000_000, + }; + match rustix::event::poll(&mut fds, Some(&timeout)) { + Ok(0) | Err(rustix::io::Errno::INTR) => continue, + Ok(_) => {} + Err(e) => return Err(format!("cannot wait for secret input: {e}")), + } + } + if signals.input_pending()? { + return Err("secret input interrupted".into()); + } + echo.restore(false)?; + Ok(value) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic)] +mod tests { + use super::*; + + #[test] + fn input_child() { + let Ok(style) = std::env::var("POSTMASTER_TEST_INPUT") else { + return; + }; + let result = read_secret("secret-ready", style != "multiline"); + if style == "prompt-error" { + assert!(result.unwrap_err().contains("prompt")); + return; + } + assert!(result.is_ok(), "input failed"); + assert_eq!(result.unwrap().trim(), "PRIVATE_SENTINEL"); + if style == "two-lines" { + assert_eq!( + read_secret("second-secret-ready", true).unwrap().trim(), + "NEXT_SENTINEL" + ); + } + } + + #[test] + fn terminal_echo_is_restored_after_success_and_error() { + for style in ["line", "multiline"] { + for outcome in ["success", "invalid-utf8"] { + let mut pty = crate::test_util::pty::TestPty::new(); + let original = tcgetattr(&pty.slave).unwrap().local_modes; + let flags = rustix::fs::fcntl_getfl(&pty.slave).unwrap(); + pty.spawn( + std::process::Command::new(std::env::current_exe().unwrap()) + .args([ + "--exact", + "keys::provisioning::input::tests::input_child", + "--nocapture", + ]) + .env("POSTMASTER_TEST_INPUT", style), + ); + pty.expect("secret-ready"); + assert!( + !tcgetattr(&pty.slave) + .unwrap() + .local_modes + .contains(LocalModes::ECHO) + ); + match outcome { + "success" => { + pty.send(b"PRIVATE_SENTINEL\n"); + if style == "multiline" { + pty.send(&[4]); + } + } + "invalid-utf8" => pty.send(&[0xff, b'\n']), + _ => pty.signal(rustix::process::Signal::TERM), + } + assert_eq!(pty.wait().success(), outcome == "success"); + assert_eq!(tcgetattr(&pty.slave).unwrap().local_modes, original); + // Darwin adds an internal status bit when the slave is written to. + assert_eq!( + rustix::fs::fcntl_getfl(&pty.slave) + .unwrap() + .contains(rustix::fs::OFlags::NONBLOCK), + flags.contains(rustix::fs::OFlags::NONBLOCK) + ); + assert!(!String::from_utf8_lossy(&pty.output).contains("PRIVATE_SENTINEL")); + } + } + } + + #[test] + fn noncanonical_single_line_retains_partial_buffered_input() { + let mut pty = crate::test_util::pty::TestPty::new(); + let mut mode = tcgetattr(&pty.slave).unwrap(); + mode.local_modes.remove(LocalModes::ICANON); + mode.special_codes[rustix::termios::SpecialCodeIndex::VMIN] = 1; + mode.special_codes[rustix::termios::SpecialCodeIndex::VTIME] = 0; + tcsetattr(&pty.slave, OptionalActions::Now, &mode).unwrap(); + pty.spawn( + std::process::Command::new(std::env::current_exe().unwrap()) + .args([ + "--exact", + "keys::provisioning::input::tests::input_child", + "--nocapture", + ]) + .env("POSTMASTER_TEST_INPUT", "line"), + ); + pty.expect("secret-ready"); + pty.send(b"PRIVATE_"); + std::thread::sleep(std::time::Duration::from_millis(100)); + pty.send(b"SENTINEL\n"); + assert!(pty.wait().success()); + assert_eq!(tcgetattr(&pty.slave).unwrap().local_modes, mode.local_modes); + assert!(!String::from_utf8_lossy(&pty.output).contains("PRIVATE_SENTINEL")); + } + + #[test] + fn idle_noncanonical_terminal_waits_for_input_and_restores_minimum() { + let mut pty = crate::test_util::pty::TestPty::new(); + let mut original = tcgetattr(&pty.slave).unwrap(); + original.local_modes.remove(LocalModes::ICANON); + original.special_codes[rustix::termios::SpecialCodeIndex::VMIN] = 0; + original.special_codes[rustix::termios::SpecialCodeIndex::VTIME] = 0; + tcsetattr(&pty.slave, OptionalActions::Now, &original).unwrap(); + pty.spawn( + std::process::Command::new(std::env::current_exe().unwrap()) + .args([ + "--exact", + "keys::provisioning::input::tests::input_child", + "--nocapture", + ]) + .env("POSTMASTER_TEST_INPUT", "line"), + ); + pty.expect("secret-ready"); + std::thread::sleep(std::time::Duration::from_millis(100)); + pty.send(b"PRIVATE_SENTINEL\n"); + assert!(pty.wait().success()); + let restored = tcgetattr(&pty.slave).unwrap(); + assert_eq!(restored.local_modes, original.local_modes); + assert_eq!( + restored.special_codes[rustix::termios::SpecialCodeIndex::VMIN], + 0 + ); + assert_eq!( + restored.special_codes[rustix::termios::SpecialCodeIndex::VTIME], + 0 + ); + } + + #[test] + fn prompt_error_returns_without_leaving_terminal_modified() { + let mut pty = crate::test_util::pty::TestPty::new(); + let original = tcgetattr(&pty.slave).unwrap().local_modes; + let flags = rustix::fs::fcntl_getfl(&pty.slave).unwrap(); + let (reader, writer) = std::io::pipe().unwrap(); + drop(reader); + pty.spawn_with_stderr( + std::process::Command::new(std::env::current_exe().unwrap()) + .args([ + "--exact", + "keys::provisioning::input::tests::input_child", + "--nocapture", + ]) + .env("POSTMASTER_TEST_INPUT", "prompt-error"), + std::process::Stdio::from(writer), + ); + assert!(pty.wait().success()); + assert_eq!(tcgetattr(&pty.slave).unwrap().local_modes, original); + assert_eq!( + rustix::fs::fcntl_getfl(&pty.slave) + .unwrap() + .contains(rustix::fs::OFlags::NONBLOCK), + flags.contains(rustix::fs::OFlags::NONBLOCK) + ); + } + + #[test] + fn successful_line_reads_preserve_the_next_queued_value() { + let mut pty = crate::test_util::pty::TestPty::new(); + pty.spawn( + std::process::Command::new(std::env::current_exe().unwrap()) + .args([ + "--exact", + "keys::provisioning::input::tests::input_child", + "--nocapture", + ]) + .env("POSTMASTER_TEST_INPUT", "two-lines"), + ); + pty.expect("secret-ready"); + pty.send(b"PRIVATE_SENTINEL\nNEXT_SENTINEL\n"); + assert!(pty.wait().success()); + assert!(!String::from_utf8_lossy(&pty.output).contains("SENTINEL")); + } +} diff --git a/src/keys/provisioning/mod.rs b/src/keys/provisioning/mod.rs new file mode 100644 index 0000000..9c78a4b --- /dev/null +++ b/src/keys/provisioning/mod.rs @@ -0,0 +1,820 @@ +//! Key provisioning — setup and verification of key sources, key +//! directory creation, keychain seeding, and runtime key source checks. +//! +//! This module implements the `postmaster setup` and `postmaster cleanup` +//! commands, plus the key-provisioning helpers they depend on. + +use std::fs; +use std::path::{Path, PathBuf}; + +use crate::exec_config::{ExecConfig, KeySourceSpec}; +use crate::server::log; + +mod cleanup; +mod input; +mod setup; + +/// The `postmaster cleanup` command, re-exported at the crate root for +/// `main()` via lib.rs. +pub use cleanup::cleanup; +/// The `postmaster setup` command, re-exported at the crate root for +/// `main()` via lib.rs. +pub use setup::setup; + +/// Default keys directory path: `/var/lib/postmaster` on Linux, +/// `~/Library/Application Support/postmaster` on macOS. +fn default_keys_dir() -> PathBuf { + #[cfg(target_os = "macos")] + { + if let Some(home) = std::env::var_os("HOME") { + return PathBuf::from(home) + .join("Library") + .join("Application Support") + .join("postmaster"); + } + } + PathBuf::from("/var/lib/postmaster") +} + +/// Create a 0700 keys directory, or check the existing directory's ownership +/// and remove group or other access. `force` affects key files and Keychain +/// items, not the directory. +#[allow(clippy::print_stderr)] +fn ensure_keys_dir(keys_dir: &Path, _force: bool) -> Result<(), String> { + if keys_dir.exists() { + // Open the directory itself and work on the fd throughout: + // O_DIRECTORY|O_NOFOLLOW rejects symlinks and non-directories at open, and + // fchmod on the fd eliminates the TOCTOU between a path-based check and a + // path-based chmod. + let dir_fd = rustix::fs::open( + keys_dir, + rustix::fs::OFlags::RDONLY + | rustix::fs::OFlags::DIRECTORY + | rustix::fs::OFlags::NOFOLLOW + | rustix::fs::OFlags::CLOEXEC, + rustix::fs::Mode::empty(), + ) + .map_err(|e| { + format!( + "{}: cannot open keys directory: {e} (refusing a symlink or non-directory)", + keys_dir.display() + ) + })?; + let stat = rustix::fs::fstat(&dir_fd) + .map_err(|e| format!("{}: fstat: {e}", keys_dir.display()))?; + if stat.st_uid != rustix::process::geteuid().as_raw() { + return Err(format!( + "{}: keys directory is owned by another user", + keys_dir.display() + )); + } + let mode = rustix::fs::Mode::from_bits_truncate(stat.st_mode); + if mode.intersects(rustix::fs::Mode::RWXG | rustix::fs::Mode::RWXO) { + // Fix permissions if we can + rustix::fs::fchmod(&dir_fd, rustix::fs::Mode::RWXU) + .map_err(|e| format!("{}: cannot fix permissions: {e}", keys_dir.display()))?; + log(&format!( + "{}: permissions corrected to 0700", + keys_dir.display() + )); + } + log(&format!("{}: keys directory verified", keys_dir.display())); + return Ok(()); + } + + // Create the directory with 0700. create_dir_all follows intermediate symlinks, so + // first reject any existing symlink component in the prefix. Residual TOCTOU: a + // component could be swapped between this check and the create, but an attacker + // with that write access could plant the symlink outright — and the open below is + // still NOFOLLOW on the final component. + let mut prefix = PathBuf::new(); + for comp in keys_dir.components() { + prefix.push(comp); + if let Ok(md) = fs::symlink_metadata(&prefix) + && md.file_type().is_symlink() + { + return Err(format!( + "{}: refusing to create keys directory through a symlinked component", + prefix.display() + )); + } + } + fs::create_dir_all(keys_dir) + .map_err(|e| format!("{}: cannot create keys directory: {e}", keys_dir.display()))?; + let dir_fd = rustix::fs::open( + keys_dir, + rustix::fs::OFlags::RDONLY + | rustix::fs::OFlags::DIRECTORY + | rustix::fs::OFlags::NOFOLLOW + | rustix::fs::OFlags::CLOEXEC, + rustix::fs::Mode::empty(), + ) + .map_err(|e| format!("{}: cannot open keys directory: {e}", keys_dir.display()))?; + let stat = + rustix::fs::fstat(&dir_fd).map_err(|e| format!("{}: stat: {e}", keys_dir.display()))?; + if stat.st_uid != rustix::process::geteuid().as_raw() { + return Err(format!( + "{}: keys directory is owned by another user", + keys_dir.display() + )); + } + rustix::fs::fchmod(&dir_fd, rustix::fs::Mode::RWXU) + .map_err(|e| format!("{}: cannot set permissions: {e}", keys_dir.display()))?; + log(&format!( + "{}: keys directory created with 0700", + keys_dir.display() + )); + Ok(()) +} + +/// Check an owned, regular key file and remove group or other access. +/// Prompt for missing contents in interactive mode; fail closed if unattended. +/// New files and forced replacements use fresh 0600 inodes. +/// +/// `--force` re-prompts for the contents even when the file is already +/// correct (manual key rotation). Force requires +/// interactive mode: unattended has no operator to paste contents. +#[allow(clippy::print_stderr)] +fn ensure_keys_file(path: &Path, force: bool, unattended: bool) -> Result<(), String> { + use crate::secret_files::{ + open_secrets_dir, replace_file, validate_directory_path, validate_projection, + }; + use rustix::fs::{AtFlags, FileType, Mode, OFlags, fstat, openat, statat}; + let parent = path + .parent() + .filter(|p| !p.as_os_str().is_empty()) + .unwrap_or(Path::new(".")); + let parent = validate_directory_path(parent)?; + let dir_fd = + open_secrets_dir(&parent).map_err(|e| format!("{}: parent: {e}", path.display()))?; + validate_projection(&dir_fd, &parent)?; + let name = path.file_name().ok_or("keys path requires a filename")?; + let original = match openat( + &dir_fd, + name, + OFlags::RDONLY | OFlags::NONBLOCK | OFlags::NOFOLLOW | OFlags::CLOEXEC, + Mode::empty(), + ) { + Ok(fd) => { + let st = fstat(&fd).map_err(|e| format!("{}: stat: {e}", path.display()))?; + if FileType::from_raw_mode(st.st_mode) != FileType::RegularFile + || st.st_uid != rustix::process::geteuid().as_raw() + || st.st_nlink != 1 + { + return Err(format!( + "{}: refusing foreign, linked or non-regular keys file", + path.display() + )); + } + if st.st_mode & 0o077 != 0 { + rustix::fs::fchmod(&fd, Mode::RUSR | Mode::WUSR) + .map_err(|e| format!("{}: chmod: {e}", path.display()))?; + log(&format!( + "{}: permissions corrected to 0600", + path.display() + )); + } + crate::secret_files::clear_file_acl(&fd)?; + if !force { + log(&format!("{}: keys file verified", path.display())); + return Ok(()); + } + Some((fd, st)) + } + Err(rustix::io::Errno::NOENT) => None, + Err(e) => { + return Err(format!( + "{}: {e} (refusing to follow a symlink)", + path.display() + )); + } + }; + if unattended { + return Err(format!( + "{}: {} (unattended mode cannot prompt)", + path.display(), + if original.is_some() { + "--force re-prompts for key contents" + } else { + "keys file not found" + } + )); + } + if original.is_some() { + eprintln!("{}: keys file exists and is valid.", path.display()); + eprintln!("--force given: replace its contents now? [y/N] "); + } else { + eprintln!("{}: keys file not found.", path.display()); + eprintln!( + "Create it now? You will need to paste the key contents (DOTENV_PRIVATE_KEY=<64-hex>...). [y/N] " + ); + } + let mut input = String::new(); + std::io::stdin() + .read_line(&mut input) + .map_err(|_| format!("{}: cannot read input", path.display()))?; + if !input.trim().eq_ignore_ascii_case("y") { + if original.is_some() { + log(&format!( + "{}: --force declined; existing keys file kept", + path.display() + )); + return Ok(()); + } + return Err(format!( + "{}: operator declined to create keys file", + path.display() + )); + } + let contents = input::read_secret("Paste the keys file contents (Ctrl+D to finish):", false)?; + if let Some((_fd, original)) = original { + let current = statat(&dir_fd, name, AtFlags::SYMLINK_NOFOLLOW) + .map_err(|e| format!("{}: stat: {e}", path.display()))?; + if current.st_dev != original.st_dev || current.st_ino != original.st_ino { + return Err(format!( + "{}: keys file changed while awaiting input", + path.display() + )); + } + replace_file(&dir_fd, name, contents.as_bytes()) + .map_err(|e| format!("{}: {e}", path.display()))?; + log(&format!( + "{}: keys file contents replaced (--force)", + path.display() + )); + } else { + let fd = openat( + &dir_fd, + name, + OFlags::WRONLY | OFlags::CREATE | OFlags::EXCL | OFlags::NOFOLLOW | OFlags::CLOEXEC, + Mode::RUSR | Mode::WUSR, + ) + .map_err(|e| { + format!( + "{}: cannot create: {e} (refusing to overwrite or follow a symlink)", + path.display() + ) + })?; + crate::secret_files::clear_file_acl(&fd)?; + rustix::fs::fchmod(&fd, Mode::RUSR | Mode::WUSR) + .map_err(|e| format!("{}: chmod: {e}", path.display()))?; + let mut file = fs::File::from(fd); + use std::io::Write as _; + if let Err(e) = file.write_all(contents.as_bytes()) { + let _ = rustix::fs::unlinkat(&dir_fd, name, AtFlags::empty()); + return Err(format!("{}: cannot write: {e}", path.display())); + } + log(&format!("{}: keys file created with 0600", path.display())); + } + Ok(()) +} + +/// Verify keychain items exist for the wanted key variables. If they +/// don't exist and we're in interactive mode, offer to seed them. +/// `--force` re-seeds every wanted item, including existing ones. macOS only. +#[cfg(target_os = "macos")] +#[allow(clippy::print_stderr)] +fn ensure_keychain_items( + service: &str, + wanted: &[String], + force: bool, + unattended: bool, +) -> Result<(), String> { + let mut missing: Vec<&str> = Vec::new(); + for var in wanted { + // Existence check via the Security.framework API — no subprocess; retrieved + // bytes zeroized on drop. + match security_framework::passwords::get_generic_password(service, var) { + Ok(bytes) => { + let _ = zeroize::Zeroizing::new(bytes); // zeroize on drop + } + Err(_) => missing.push(var), + } + } + + // --force re-seeds every wanted item, present or not; without it only the missing + // ones are offered. + let to_seed: Vec<&str> = if force { + wanted.iter().map(String::as_str).collect() + } else { + missing + }; + + if to_seed.is_empty() { + log(&format!( + "keychain {service}: all {wanted_len} item(s) verified", + wanted_len = wanted.len() + )); + return Ok(()); + } + + if unattended { + return Err(format!( + "keychain {service}: {seed_len} item(s) to seed (unattended mode — cannot prompt)", + seed_len = to_seed.len() + )); + } + + // Interactive: offer to seed + eprintln!("keychain {service}: items to seed: {}", to_seed.join(", ")); + eprintln!("Seed them now? You will need to paste each key value. [y/N] "); + let mut input = String::new(); + if std::io::stdin().read_line(&mut input).is_err() { + return Err("cannot read input".into()); + } + if !input.trim().eq_ignore_ascii_case("y") { + return Err(format!( + "keychain {service}: operator declined to seed items" + )); + } + + for var in &to_seed { + let value = input::read_secret(&format!("Paste value for {var}:"), true)?; + let value = value.trim(); + if value.is_empty() { + return Err(format!("{var}: empty value, refusing to seed")); + } + // Seed via the Security.framework API, not the security CLI: + // `add-generic-password -w ` exposes key material in the subprocess + // argv, readable by any local process via ps / proc_pidinfo. + security_framework::passwords::set_generic_password(service, var, value.as_bytes()) + .map_err(|e| format!("keychain {service}: failed to seed {var}: {e}"))?; + log(&format!("keychain {service}: seeded {var}")); + } + + Ok(()) +} + +/// Check configured key-source prerequisites without decrypting values. +/// File sources get descriptor-based access checks; credentials get presence +/// and type checks. Keychain and environment sources check required names. +fn verify_key_sources(cfg: &ExecConfig, wanted: &[String]) -> Result<(), String> { + // `wanted` is only consulted by the macOS keychain check below. + #[cfg(not(target_os = "macos"))] + let _ = wanted; + let mut checked = 0_u32; + + for spec in &cfg.keys { + match spec { + KeySourceSpec::Credential(name) => { + checked += 1; + let dir = std::env::var_os("CREDENTIALS_DIRECTORY") + .ok_or("$CREDENTIALS_DIRECTORY is not set")?; + let p = Path::new(&dir).join(name); + // Mirror load_ring's discipline: verification must not pass what + // resolution rejects — exists() follows symlinks, but the loader + // refuses a symlinked credential outright. + match fs::symlink_metadata(&p) { + Ok(md) if md.file_type().is_symlink() => { + return Err(format!( + "{}: credential source is a symlink; refusing to follow", + p.display() + )); + } + Ok(md) if md.is_file() => {} + Ok(_) => { + return Err(format!( + "{}: credential source is not a regular file", + p.display() + )); + } + Err(e) if e.kind() == std::io::ErrorKind::NotFound => { + return Err(format!( + "{}: credential source not found under $CREDENTIALS_DIRECTORY", + p.display() + )); + } + Err(e) => { + return Err(format!( + "{}: cannot stat credential source: {e}", + p.display() + )); + } + } + } + KeySourceSpec::File(path) => { + checked += 1; + if path.starts_with("/nix/store") { + return Err(format!( + "{}: refusing plaintext private keys from the world-readable Nix store", + path.display() + )); + } + // NONBLOCK is inert on regular files and prevents a FIFO from hanging + // verification at open; the file-type check then rejects anything that + // isn't a regular file. + let oflags = rustix::fs::OFlags::RDONLY + | rustix::fs::OFlags::NOFOLLOW + | rustix::fs::OFlags::CLOEXEC + | rustix::fs::OFlags::NONBLOCK; + let fd = + rustix::fs::open(path, oflags, rustix::fs::Mode::empty()).map_err(|e| { + format!("{}: {e} (refusing to follow a symlink)", path.display()) + })?; + let stat = rustix::fs::fstat(&fd) + .map_err(|e| format!("{}: fstat: {e}", path.display()))?; + if !rustix::fs::FileType::from_raw_mode(stat.st_mode).is_file() { + return Err(format!( + "{}: not a regular file (fail closed)", + path.display() + )); + } + let mode = rustix::fs::Mode::from_bits_truncate(stat.st_mode); + if mode.intersects(rustix::fs::Mode::RWXG | rustix::fs::Mode::RWXO) { + return Err(format!( + "{}: permissions {:#o} are group/world accessible; expected 0400 or 0600", + path.display(), + stat.st_mode + )); + } + let euid = rustix::process::geteuid().as_raw(); + if stat.st_uid != euid { + return Err(format!( + "{}: owned by uid {} but postmaster euid is {euid}", + path.display(), + stat.st_uid + )); + } + crate::secret_files::validate_private_file_acl(&fd) + .map_err(|e| format!("{}: {e}", path.display()))?; + } + KeySourceSpec::Keychain(service) => { + #[cfg(target_os = "macos")] + { + checked += 1; + for var in wanted { + // Security.framework API — no subprocess; retrieved bytes + // zeroized on drop. + match security_framework::passwords::get_generic_password(service, var) { + Ok(bytes) => { + let _ = zeroize::Zeroizing::new(bytes); // zeroize on drop + } + Err(_) => { + return Err(format!( + "keychain {service}: no item for account {var} (fail closed)" + )); + } + } + } + } + #[cfg(not(target_os = "macos"))] + { + let _ = service; + return Err("keychain source is only available on macOS".into()); + } + } + KeySourceSpec::Environment => { + checked += 1; + // Require each adapter namespace with the same exact-prefix predicate + // as KeyRing::from_env; unrelated keys must not satisfy setup checks. + for naming in cfg.required_namings() { + let prefix = naming.key_prefix(); + // vars_os: std::env::vars() panics during iteration on non-Unicode + // entries — an abort under panic=abort, not a clean verification + // failure. + if !std::env::vars_os().any(|(k, _)| { + k.to_str() + .is_some_and(|k| crate::keys::is_key_var_name(prefix, k)) + }) { + return Err(format!("environment: no {prefix}* variables set")); + } + } + } + } + } + + if checked == 0 { + return Err("no key sources configured (configure keys=[…])".into()); + } + + // Every per-source failure above early-returns, so reaching the log means checked + // == verified — report the count, not a fraction that is always N/N. + log(&format!( + "setup: {checked} key source(s) verified — environment ready" + )); + Ok(()) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic)] +mod tests { + use super::*; + use crate::adapter::KeyNaming; + use crate::test_util::ENV_LOCK; + + fn env_only_cfg() -> ExecConfig { + serde_json::from_str(r#"{"mode":"env","keys":["environment"],"env_files":["/x/.env"]}"#) + .unwrap() + } + + #[test] + fn verify_key_sources_uses_from_env_predicate() { + // Verification must admit exactly what KeyRing::from_env admits. A + // prefix-substring collision like DOTENV_PRIVATE_KEYFOO is NOT a key var, so + // with only such a var set, verification must fail. + let _guard = ENV_LOCK.lock().unwrap(); + let cfg = env_only_cfg(); + let bogus = "DOTENV_PRIVATE_KEYFOO_PMVERIFY"; + let valid = "DOTENV_PRIVATE_KEY_PMVERIFY"; + + // Positive leg: an exact `PREFIX_` var passes. Robust + // against any valid key vars ambient in the test runner's own + // environment. + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + unsafe { + std::env::set_var(valid, "aa".repeat(32)); + } + assert!( + verify_key_sources(&cfg, &[]).is_ok(), + "an exact PREFIX_ variable must pass verification" + ); + + // Negative leg: only a prefix-substring collision remains. + unsafe { + std::env::remove_var(valid); + std::env::set_var(bogus, "aa".repeat(32)); + } + let res = verify_key_sources(&cfg, &[]); + unsafe { + std::env::remove_var(bogus); + } + // Guard against an ambient valid key var in the test runner's + // own environment (e.g. DOTENV_PRIVATE_KEY exported in CI): if + // one is present, the negative leg is not observable — skip + // rather than flake. A concurrent test cannot be the source: + // every env-mutating test holds the shared ENV_LOCK. Only the + // Env prefix counts here: this config requires Env naming alone. + let any_valid = std::env::vars() + .any(|(k, _)| crate::keys::is_key_var_name(KeyNaming::Env.key_prefix(), &k)); + if !any_valid { + let err = res.expect_err("a prefix-substring variable must fail verification"); + assert!(err.contains("environment:"), "{err}"); + } + } + + #[test] + fn verify_key_sources_credential_rejects_symlink() { + // Rechecks must reject symlinks just as runtime loading does. + use std::os::unix::fs::PermissionsExt; + let d = crate::test_util::temp_dir::TestDir::new("mod"); + let cred_dir = d.join("creds"); + fs::create_dir_all(&cred_dir).unwrap(); + let real = d.join("real-keys"); + fs::write(&real, format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32))).unwrap(); + fs::set_permissions(&real, fs::Permissions::from_mode(0o600)).unwrap(); + std::os::unix::fs::symlink(&real, cred_dir.join("link-keys")).unwrap(); + + let cfg: ExecConfig = serde_json::from_str( + r#"{"mode":"env","keys":[{"credential":"link-keys"}],"env_files":["/x/.env"]}"#, + ) + .unwrap(); + + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + unsafe { + std::env::set_var("CREDENTIALS_DIRECTORY", &cred_dir); + } + let res = verify_key_sources(&cfg, &[]); + unsafe { + std::env::remove_var("CREDENTIALS_DIRECTORY"); + } + let _ = fs::remove_dir_all(&d); + let err = res.expect_err("a symlinked credential must fail verification"); + assert!(err.contains("symlink"), "{err}"); + } + + #[test] + fn ensure_keys_file_force_unattended_fails_closed() { + // --force re-prompts for contents, which unattended mode cannot do — fail + // closed rather than silently skipping the re-create the operator asked for. + use std::os::unix::fs::PermissionsExt; + let d = crate::test_util::temp_dir::TestDir::new("mod"); + let keys = d.join(".env.keys"); + let contents = format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32)); + fs::write(&keys, &contents).unwrap(); + fs::set_permissions(&keys, fs::Permissions::from_mode(0o600)).unwrap(); + + let err = + ensure_keys_file(&keys, true, true).expect_err("force + unattended must fail closed"); + let verification = ensure_keys_file(&keys, false, true); + if crate::test_util::root_has_trusted_owner() { + assert!(err.contains("unattended"), "{err}"); + verification.expect("valid file must verify without force"); + } else { + assert_eq!(err, "/: directory path is owned by an untrusted user"); + assert_eq!(verification.unwrap_err(), err); + } + assert_eq!(fs::read_to_string(&keys).unwrap(), contents); + let _ = fs::remove_dir_all(&d); + } + + fn bundle_only_cfg() -> ExecConfig { + serde_json::from_str( + r#"{"mode":"env","keys":["environment"],"bundle_files":["/x/s.json"]}"#, + ) + .unwrap() + } + + fn mixed_cfg() -> ExecConfig { + serde_json::from_str( + r#"{"mode":"env","keys":["environment"],"env_files":["/x/.env"],"bundle_files":["/x/s.json"]}"#, + ) + .unwrap() + } + + /// True when a valid key var for `prefix` exists that this test did + /// NOT set itself (i.e. ambient in the runner's own environment). + fn ambient_key_var(prefix: &str, mine: &[&str]) -> bool { + std::env::vars() + .any(|(k, _)| !mine.contains(&k.as_str()) && crate::keys::is_key_var_name(prefix, &k)) + } + + #[test] + fn verify_key_sources_requires_each_required_naming() { + // The compounding half of the bundle-ring gap: verification used + // to accept EITHER prefix for the environment source, so an + // env-files-only config passed with only POSTMASTER_KEY present + // (then failed at exec), and a bundle-only config failed despite + // its POSTMASTER_KEY being right there. Every required naming + // must now be present. + // + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + let dotenv = "DOTENV_PRIVATE_KEY_PMREQUIRED"; + let bundle = "POSTMASTER_KEY_PMREQUIRED"; + let key_hex = "aa".repeat(32); + unsafe { + std::env::remove_var(dotenv); + std::env::remove_var(bundle); + } + + // bundle-only config + its POSTMASTER_KEY present → passes. + unsafe { + std::env::set_var(bundle, &key_hex); + } + assert!( + verify_key_sources(&bundle_only_cfg(), &[]).is_ok(), + "a bundle config's own POSTMASTER_KEY must satisfy verification" + ); + + // env-only config + only bundle material → fails (the old lie). + let res = verify_key_sources(&env_only_cfg(), &[]); + if !ambient_key_var(KeyNaming::Env.key_prefix(), &[dotenv, bundle]) { + let err = res.expect_err("POSTMASTER_KEY must not satisfy an env-only config"); + assert!(err.contains("DOTENV_PRIVATE_KEY"), "{err}"); + } + + // mixed config with only ONE of the two required namings → fails. + unsafe { + std::env::remove_var(bundle); + std::env::set_var(dotenv, &key_hex); + } + let res = verify_key_sources(&mixed_cfg(), &[]); + if !ambient_key_var(KeyNaming::Bundle.key_prefix(), &[dotenv, bundle]) { + let err = res.expect_err("a mixed config requires POSTMASTER_KEY too"); + assert!(err.contains("POSTMASTER_KEY"), "{err}"); + } + + // mixed config with both required namings present → passes. + unsafe { + std::env::set_var(bundle, &key_hex); + } + assert!( + verify_key_sources(&mixed_cfg(), &[]).is_ok(), + "both required namings present must pass" + ); + + unsafe { + std::env::remove_var(dotenv); + std::env::remove_var(bundle); + } + } + + #[test] + fn ensure_keys_dir_creates_0700_and_corrects_wide_modes() { + // Creation and repair must both leave the directory at 0700. + use std::os::unix::fs::PermissionsExt; + // Canonicalize the temp base: on macOS it sits under /var → + // /private/var, and the directory-prefix walk would refuse + // the symlinked /var component for reasons unrelated to this test. + let d = crate::test_util::temp_dir::TestDir::new("mod"); + + let created = d.join("new-keys"); + ensure_keys_dir(&created, false).expect("create should succeed"); + let mode = fs::metadata(&created).unwrap().permissions().mode() & 0o777; + assert_eq!(mode, 0o700, "fresh keys dir must be 0700, got {mode:o}"); + + let wide = d.join("wide-keys"); + fs::create_dir_all(&wide).unwrap(); + fs::set_permissions(&wide, fs::Permissions::from_mode(0o755)).unwrap(); + ensure_keys_dir(&wide, false).expect("verify/correct should succeed"); + let mode = fs::metadata(&wide).unwrap().permissions().mode() & 0o777; + assert_eq!(mode, 0o700, "a 0755 keys dir must be corrected to 0700"); + + let _ = fs::remove_dir_all(&d); + } + + #[test] + fn ensure_keys_dir_refuses_a_symlinked_prefix() { + // create_dir_all follows intermediate symlinks, so the prefix walk must refuse + // them before anything is created. Canonicalize the temp base (macOS /var → + // /private/var) so the walk reaches OUR planted symlink instead of refusing the + // OS-provided /var component first. + let d = crate::test_util::temp_dir::TestDir::new("mod"); + let real = d.join("real"); + fs::create_dir_all(&real).unwrap(); + std::os::unix::fs::symlink(&real, d.join("link")).unwrap(); + + let err = ensure_keys_dir(&d.join("link").join("keys"), false) + .expect_err("a symlinked path component must be refused"); + assert!(err.contains("symlink"), "{err}"); + assert!( + !real.join("keys").exists(), + "nothing may be created through the symlink" + ); + + let _ = fs::remove_dir_all(&d); + } + + #[test] + fn ensure_keys_file_corrects_mode_and_missing_unattended_fails() { + // A 0644 keys file is corrected to 0600; a missing file in unattended mode + // fails closed (no prompt). + use std::os::unix::fs::PermissionsExt; + let d = crate::test_util::temp_dir::TestDir::new("mod"); + let keys = d.join(".env.keys"); + let contents = format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32)); + fs::write(&keys, &contents).unwrap(); + fs::set_permissions(&keys, fs::Permissions::from_mode(0o644)).unwrap(); + + let verification = ensure_keys_file(&keys, false, true); + let mode = fs::metadata(&keys).unwrap().permissions().mode() & 0o777; + + let missing = d.join("absent.keys"); + let err = ensure_keys_file(&missing, false, true) + .expect_err("missing file + unattended must fail closed"); + if crate::test_util::root_has_trusted_owner() { + verification.expect("verify/correct should succeed"); + assert_eq!(mode, 0o600, "a 0644 keys file must be corrected to 0600"); + assert!(err.contains("unattended mode"), "{err}"); + } else { + assert_eq!(err, "/: directory path is owned by an untrusted user"); + assert_eq!(verification.unwrap_err(), err); + assert_eq!(mode, 0o644, "untrusted ancestry must prevent mutation"); + } + assert_eq!(fs::read_to_string(&keys).unwrap(), contents); + assert!(!missing.exists()); + + let _ = fs::remove_dir_all(&d); + } + + #[test] + fn keys_files_reject_linked_special_and_foreign_inodes_before_mutation() { + use std::os::unix::fs::PermissionsExt as _; + let dir = crate::test_util::temp_dir::TestDir::new("key-custody"); + let path = dir.join("keys"); + fs::write(&path, b"unchanged").unwrap(); + fs::set_permissions(&path, fs::Permissions::from_mode(0o644)).unwrap(); + fs::hard_link(&path, dir.join("link")).unwrap(); + assert!(ensure_keys_file(&path, false, true).is_err()); + assert_eq!( + fs::metadata(&path).unwrap().permissions().mode() & 0o777, + 0o644 + ); + fs::remove_file(&path).unwrap(); + assert!( + std::process::Command::new("mkfifo") + .arg(&path) + .status() + .unwrap() + .success() + ); + assert!(ensure_keys_file(&path, false, true).is_err()); + if rustix::process::geteuid().is_root() { + fs::remove_file(&path).unwrap(); + fs::write(&path, b"foreign").unwrap(); + fs::set_permissions(&path, fs::Permissions::from_mode(0o644)).unwrap(); + rustix::fs::chown(&path, Some(rustix::fs::Uid::from_raw(65534)), None).unwrap(); + assert!(ensure_keys_file(&path, false, true).is_err()); + assert_eq!( + fs::metadata(&path).unwrap().permissions().mode() & 0o777, + 0o644 + ); + let foreign = dir.join("directory"); + fs::create_dir(&foreign).unwrap(); + fs::set_permissions(&foreign, fs::Permissions::from_mode(0o755)).unwrap(); + rustix::fs::chown(&foreign, Some(rustix::fs::Uid::from_raw(65534)), None).unwrap(); + assert!(ensure_keys_dir(&foreign, false).is_err()); + assert_eq!( + fs::metadata(&foreign).unwrap().permissions().mode() & 0o777, + 0o755 + ); + } + } +} diff --git a/src/keys/provisioning/setup.rs b/src/keys/provisioning/setup.rs new file mode 100644 index 0000000..33242bf --- /dev/null +++ b/src/keys/provisioning/setup.rs @@ -0,0 +1,123 @@ +//! `postmaster setup` command path. + +use std::collections::HashSet; +use std::path::{Path, PathBuf}; + +#[cfg(target_os = "macos")] +use super::ensure_keychain_items; +use super::{default_keys_dir, ensure_keys_dir, ensure_keys_file, verify_key_sources}; +use crate::adapter::KeyNaming; +use crate::exec_config::{ExecConfig, KeySourceSpec}; +use crate::server::log; + +/// Resolve distinct setup key variables in first-seen input order. +fn wanted_keys(cfg: &ExecConfig) -> Result, String> { + let mut wanted = Vec::new(); + for f in &cfg.env_files { + wanted.push(KeyNaming::Env.key_var_for(f)?); + } + for f in &cfg.bundle_files { + wanted.push(KeyNaming::Bundle.key_var_for(f)?); + } + let mut seen = HashSet::new(); + wanted.retain(|key| seen.insert(key.clone())); + Ok(wanted) +} + +/// `postmaster setup`: verify platform prerequisites, create keys +/// directory with correct permissions, optionally seed keychain items, +/// and validate the environment. Idempotent — skips steps that are +/// already correct. +/// +/// `--recheck`: re-run verification checks only, without creating or +/// modifying anything. +/// +/// `--unattended`: non-interactive mode for automation. Uses defaults +/// or env vars instead of prompting. Fail closed on any missing +/// prerequisite. +/// +/// `--force`: re-seed or re-create even if the target state is already +/// present. +/// +/// `--keys-dir `: override the keys directory path. +pub fn setup( + config_path: &Path, + recheck: bool, + unattended: bool, + force: bool, + keys_dir_override: Option, +) -> Result<(), String> { + let cfg = crate::launcher::parse_exec_config(config_path)?; + cfg.validate_shape()?; + + let wanted = wanted_keys(&cfg)?; + + if recheck { + // --recheck: verification only, no creation or modification + return verify_key_sources(&cfg, &wanted); + } + + // Step 1: Create or verify keys directory + let keys_dir = keys_dir_override.unwrap_or_else(default_keys_dir); + ensure_keys_dir(&keys_dir, force)?; + + // Step 2: Verify or create key files for file-source keys + for spec in &cfg.keys { + if let KeySourceSpec::File(path) = spec { + ensure_keys_file(path, force, unattended)?; + } + } + + // Step 3: Verify or seed keychain items (macOS only) + #[cfg(target_os = "macos")] + for spec in &cfg.keys { + if let KeySourceSpec::Keychain(service) = spec { + ensure_keychain_items(service, &wanted, force, unattended)?; + } + } + + // Step 4: Verify the full environment (same as --recheck) + verify_key_sources(&cfg, &wanted)?; + + log(&format!( + "setup: complete — keys dir {}, {} key source(s) verified", + keys_dir.display(), + cfg.keys.len() + )); + Ok(()) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used)] +mod tests { + use super::*; + + #[test] + fn setup_keys_are_unique_and_keep_first_seen_order() { + let mut cfg: ExecConfig = serde_json::from_value(serde_json::json!({ + "mode": "env", "keys": [{"keychain": "postmaster"}], + "bundle_files": ["/x/first.json", "/x/second.json"] + })) + .unwrap(); + assert_eq!(wanted_keys(&cfg).unwrap(), ["POSTMASTER_KEY"]); + cfg.env_files = [ + "/x/.env.production", + "/x/.env", + "/y/.env.production", + "/x/.env.development", + ] + .map(PathBuf::from) + .into(); + assert_eq!( + wanted_keys(&cfg).unwrap(), + [ + "DOTENV_PRIVATE_KEY_PRODUCTION", + "DOTENV_PRIVATE_KEY", + "DOTENV_PRIVATE_KEY_DEVELOPMENT", + "POSTMASTER_KEY" + ] + ); + cfg.env_files.push("/x/.env.bad-name".into()); + assert!(wanted_keys(&cfg).is_err()); + } +} diff --git a/src/keys/source.rs b/src/keys/source.rs new file mode 100644 index 0000000..5afe618 --- /dev/null +++ b/src/keys/source.rs @@ -0,0 +1,393 @@ +//! Key source selection — loads the private key ring from the first +//! available source per the exec config's ordered `keys` list. +//! +//! `credential` is skippable (absent `$CREDENTIALS_DIRECTORY` or file ⇒ +//! try the next source); every other source is terminal: once selected, +//! its failure fails the launcher. + +use std::fs; +use std::path::Path; + +use crate::adapter::KeyNaming; +use crate::exec_config::KeySourceSpec; +use crate::keys::KeyRing; + +/// Ordered key-source selection. `credential` is skippable (no +/// $CREDENTIALS_DIRECTORY or file absent ⇒ try next source); every other +/// source is terminal: once selected, its failure fails the launcher. +/// +/// `namings` is the adapter set the config's artifacts require +/// (`ExecConfig::required_namings`): the ring admits exactly those key +/// prefixes, including both namespaces for mixed dotenv and bundle inputs. +// `wanted_vars` is only consumed by the macOS keychain source; on other +// targets the parameter is unused, so silence that leg's clippy warning +// without touching the signature or source-selection semantics. +#[cfg_attr(not(target_os = "macos"), allow(unused_variables))] +pub fn load_ring( + specs: &[KeySourceSpec], + wanted_vars: &[String], + namings: &[KeyNaming], +) -> Result { + for spec in specs { + match spec { + KeySourceSpec::Credential(name) => { + if let Some(dir) = std::env::var_os("CREDENTIALS_DIRECTORY") { + let p = Path::new(&dir).join(name); + // Use symlink_metadata instead of p.exists(): exists() follows + // symlinks, so a planted symlink at $CREDENTIALS_DIRECTORY/ + // pointing to a world-readable file would be silently followed. + // Reject symlinks outright; the subsequent KeyRing::load also opens + // with O_NOFOLLOW as defense-in-depth. + match fs::symlink_metadata(&p) { + Ok(md) if md.file_type().is_symlink() => { + return Err(format!( + "{}: credential source is a symlink; refusing to follow (remove the symlink)", + p.display() + )); + } + Ok(md) if md.is_file() => return KeyRing::load(&p, namings), + Ok(_) => { + return Err(format!( + "{}: credential source is not a regular file", + p.display() + )); + } + Err(e) if e.kind() == std::io::ErrorKind::NotFound => { + // absent: fall through to next source + } + // A permission-denied or malformed credential dir is NOT + // "absent" — it is misconfigured. Fail loudly rather than + // silently selecting a source the operator didn't expect. + Err(e) => { + return Err(format!( + "{}: cannot stat credential source: {e}", + p.display() + )); + } + } + } + // absent credential: fall through to the next source + } + KeySourceSpec::File(p) => { + if p.starts_with("/nix/store") { + return Err(format!( + "{}: refusing plaintext private keys from the world-readable Nix store", + p.display() + )); + } + return KeyRing::load(p, namings); + } + KeySourceSpec::Keychain(service) => { + #[cfg(target_os = "macos")] + return KeyRing::from_keychain(service, wanted_vars, namings); + #[cfg(not(target_os = "macos"))] + return Err(format!( + "key source keychain({service}) is only available on macOS" + )); + } + KeySourceSpec::Environment => return KeyRing::from_env(namings), + } + } + Err("no usable key source (configure keys=[…] or set DOTENV_PRIVATE_KEY*)".into()) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic, unused_qualifications)] +mod tests { + use super::*; + use crate::exec_config::KeySourceSpec; + use crate::test_util::ENV_LOCK; + + #[test] + fn load_ring_credential_is_skippable() { + // credential source with no CREDENTIALS_DIRECTORY set should fall + // through to the next source. Here the next source is "environment", + // which is terminal and will fail closed (no DOTENV_PRIVATE_KEY* + // vars in the test runner). The error must be from the environment + // source, not from the credential source. + // + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + unsafe { + std::env::remove_var("CREDENTIALS_DIRECTORY"); + } + // Guard against an ambient valid key var in the test runner's own environment + // (e.g. DOTENV_PRIVATE_KEY exported in CI): with one present, the environment + // source SUCCEEDS and the terminal error is unobservable — skip rather than + // flake. Only the Env prefix counts here: these namings require Env alone. + let ambient = std::env::vars_os().any(|(k, _)| { + k.to_str() + .is_some_and(|k| crate::keys::is_key_var_name(KeyNaming::Env.key_prefix(), k)) + }); + if ambient { + return; + } + let specs = vec![ + KeySourceSpec::Credential("nonexistent".to_string()), + KeySourceSpec::Environment, + ]; + let err = load_ring(&specs, &[], &[KeyNaming::Env]).unwrap_err(); + // The error must come from the environment source (terminal), + // proving credential fell through rather than erroring. + assert!( + err.contains("environment:"), + "credential should be skippable; got: {err}" + ); + } + + #[test] + fn load_ring_credential_rejects_symlink() { + // A symlink planted at $CREDENTIALS_DIRECTORY/ must be rejected, not + // followed. + use std::os::unix::fs::PermissionsExt; + let d = crate::test_util::temp_dir::TestDir::new("source"); + let real = d.join("real-keys"); + fs::write(&real, format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32))).unwrap(); + fs::set_permissions(&real, fs::Permissions::from_mode(0o600)).unwrap(); + let cred_dir = d.join("creds"); + fs::create_dir_all(&cred_dir).unwrap(); + let link = cred_dir.join("dotenv-private-key"); + std::os::unix::fs::symlink(&real, &link).unwrap(); + + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + unsafe { + std::env::set_var("CREDENTIALS_DIRECTORY", &cred_dir); + } + let specs = vec![KeySourceSpec::Credential("dotenv-private-key".to_string())]; + let err = load_ring(&specs, &[], &[KeyNaming::Env]).unwrap_err(); + unsafe { + std::env::remove_var("CREDENTIALS_DIRECTORY"); + } + assert!( + err.contains("symlink"), + "credential symlink should be rejected; got: {err}" + ); + } + + #[test] + fn load_ring_credential_stat_error_is_terminal() { + // A permission-denied credential dir is misconfigured, not "absent" — it must + // hard-error rather than fall through to the next source. + use std::os::unix::fs::PermissionsExt; + if rustix::process::geteuid().is_root() { + // chmod 000 does not exclude root; the EACCES leg is + // unobservable in a root test run. + return; + } + let d = crate::test_util::temp_dir::TestDir::new("source"); + let cred_dir = d.join("locked"); + fs::create_dir_all(&cred_dir).unwrap(); + fs::set_permissions(&cred_dir, fs::Permissions::from_mode(0o000)).unwrap(); + + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + unsafe { + std::env::set_var("CREDENTIALS_DIRECTORY", &cred_dir); + } + let specs = vec![ + KeySourceSpec::Credential("keys".to_string()), + KeySourceSpec::Environment, + ]; + let err = load_ring(&specs, &[], &[KeyNaming::Env]).unwrap_err(); + unsafe { + std::env::remove_var("CREDENTIALS_DIRECTORY"); + } + fs::set_permissions(&cred_dir, fs::Permissions::from_mode(0o700)).unwrap(); + let _ = fs::remove_dir_all(&d); + assert!( + err.contains("cannot stat credential source"), + "stat failure must be terminal, not a fall-through; got: {err}" + ); + } + + #[test] + fn load_ring_credential_rejects_non_file() { + // A directory as a credential source name should be rejected, + // not silently skipped or treated as a file. + let d = crate::test_util::temp_dir::TestDir::new("source"); + let cred_dir = d.join("creds"); + fs::create_dir_all(&cred_dir).unwrap(); + let sub = cred_dir.join("subdir"); + fs::create_dir_all(&sub).unwrap(); + + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + unsafe { + std::env::set_var("CREDENTIALS_DIRECTORY", &cred_dir); + } + let specs = vec![KeySourceSpec::Credential("subdir".to_string())]; + let err = load_ring(&specs, &[], &[KeyNaming::Env]).unwrap_err(); + unsafe { + std::env::remove_var("CREDENTIALS_DIRECTORY"); + } + assert!( + err.contains("not a regular file"), + "credential directory should be rejected; got: {err}" + ); + } + + #[test] + fn load_ring_file_is_terminal() { + // file source with a nonexistent path should return an error + // immediately, NOT fall through to the next source. We verify this + // by putting a valid "environment" source after the bad file source: + // if file were skippable, load_ring would try environment and fail + // with "environment:" — instead it must fail with the file path. + let fixture = crate::test_util::temp_dir::TestDir::new("missing-source"); + let ghost_path = fixture.join("ghost.keys"); + let specs = vec![ + KeySourceSpec::File(ghost_path.clone()), + KeySourceSpec::Environment, + ]; + let err = load_ring(&specs, &[], &[KeyNaming::Env]).unwrap_err(); + assert!( + err.contains("ghost.keys"), + "file source should be terminal and error with the path; got: {err}" + ); + } + + #[test] + fn load_ring_file_rejects_nix_store() { + // file source under /nix/store must return immediately with an + // error, not fall through to a subsequent source. + let specs = vec![ + KeySourceSpec::File(std::path::PathBuf::from("/nix/store/abc/.env.keys")), + KeySourceSpec::Environment, + ]; + let err = load_ring(&specs, &[], &[KeyNaming::Env]).unwrap_err(); + assert!( + err.contains("Nix store"), + "file source under /nix/store should be terminal and reject; got: {err}" + ); + } + + #[test] + fn load_ring_environment_is_terminal() { + // environment source with no DOTENV_PRIVATE_KEY* vars should return + // an error immediately, not fall through. Since it's the last source, + // we verify the error is from from_env, not from the "no usable key + // source" fallback message. + // + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + let var_name = "DOTENV_PRIVATE_KEY_TESTTERMINAL"; + unsafe { + std::env::remove_var(var_name); + } + let specs = vec![ + KeySourceSpec::Credential("skipped".to_string()), + KeySourceSpec::Environment, + ]; + // Remove CREDENTIALS_DIRECTORY so credential is skippable. + unsafe { + std::env::remove_var("CREDENTIALS_DIRECTORY"); + } + let err = load_ring(&specs, &[], &[KeyNaming::Env]).unwrap_err(); + // The error must be from environment (terminal), not "no usable key + // source" (which would mean environment also fell through). + assert!( + !err.contains("no usable key source"), + "environment should be terminal, not fall through; got: {err}" + ); + } + + #[test] + fn load_ring_admits_bundle_naming_when_required() { + // Regression for the bundle-ring gap: load_ring used to hardcode + // KeyNaming::Env at every source leg, so POSTMASTER_KEY material + // never entered the ring and every bundle config failed at + // resolve_bundle time. With Bundle in the required namings, the + // environment source must admit it. + // + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + let var_name = "POSTMASTER_KEY_TESTLOADRING"; + unsafe { + std::env::set_var(var_name, "aa".repeat(32)); + } + let specs = vec![KeySourceSpec::Environment]; + let ring = load_ring(&specs, &[], &[KeyNaming::Bundle]); + unsafe { + std::env::remove_var(var_name); + } + let ring = + ring.expect("environment source must admit POSTMASTER_KEY* when Bundle is required"); + assert!(ring.candidates(var_name).is_some()); + } + + #[test] + fn load_ring_excludes_unrequired_namings() { + // Least privilege: a bundle config's ring must NOT carry + // DOTENV_PRIVATE_KEY* material just because the source provides + // it, and vice versa — the ring admits exactly the required set. + // + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + let dotenv_var = "DOTENV_PRIVATE_KEY_TESTLOADRING"; + let bundle_var = "POSTMASTER_KEY_TESTLOADRING"; + unsafe { + std::env::set_var(dotenv_var, "bb".repeat(32)); + std::env::set_var(bundle_var, "cc".repeat(32)); + } + let specs = vec![KeySourceSpec::Environment]; + let ring = load_ring(&specs, &[], &[KeyNaming::Bundle]); + unsafe { + std::env::remove_var(dotenv_var); + std::env::remove_var(bundle_var); + } + let ring = ring.expect("bundle-required ring should load from POSTMASTER_KEY*"); + assert!(ring.candidates(bundle_var).is_some()); + assert!( + ring.candidates(dotenv_var).is_none(), + "an unrequired naming must not enter the ring" + ); + } + + #[test] + fn load_ring_credential_loads_present_file() { + // The positive credential leg — a present, well-formed credential file loads + // through the same selection path the negative legs reject. + use std::os::unix::fs::PermissionsExt; + let d = crate::test_util::temp_dir::TestDir::new("source"); + let cred_dir = d.join("creds"); + fs::create_dir_all(&cred_dir).unwrap(); + let cred = cred_dir.join("dotenv-keys"); + fs::write(&cred, format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32))).unwrap(); + fs::set_permissions(&cred, fs::Permissions::from_mode(0o600)).unwrap(); + + // SAFETY: set_var/remove_var are unsafe on edition 2024 (not + // thread-safe). Serialized via the process-wide ENV_LOCK + // (crate::test_util) shared by every env-mutating test. + let _guard = ENV_LOCK.lock().unwrap(); + unsafe { + std::env::set_var("CREDENTIALS_DIRECTORY", &cred_dir); + } + let ring = load_ring( + &[KeySourceSpec::Credential("dotenv-keys".to_string())], + &[], + &[KeyNaming::Env], + ); + unsafe { + std::env::remove_var("CREDENTIALS_DIRECTORY"); + } + let _ = fs::remove_dir_all(&d); + + let ring = ring.expect("a present credential file must load"); + assert!(ring.candidates("DOTENV_PRIVATE_KEY").is_some()); + } +} diff --git a/src/keys/verify.rs b/src/keys/verify.rs new file mode 100644 index 0000000..91cb096 --- /dev/null +++ b/src/keys/verify.rs @@ -0,0 +1,138 @@ +//! Integrity verification of external binaries invoked on +//! secret-handling paths. + +use std::path::Path; + +/// Check platform trust requirements before invoking an external helper. +/// +/// On macOS, `codesign -v ` checks the code signature. Callers use +/// fixed system paths protected by SIP. +/// +/// On Linux: verify the file is a regular file, owned by root (uid 0), +/// and not writable by group or others. These are ownership and permission +/// checks, not a content-signature check. +/// +/// Bootstrap limitation: on macOS the verifier +/// itself invokes `/usr/bin/codesign`. Self-verifying codesign with +/// codesign is circular — a compromised codesign would vouch for +/// itself. The verifier trusts the system's SIP protection for that tool. +pub fn verify_external_binary(path: &Path) -> Result<(), String> { + #[cfg(target_os = "macos")] + { + let out = std::process::Command::new("/usr/bin/codesign") + .args(["-v", path.to_str().unwrap_or("")]) + .output() + .map_err(|e| format!("{}: codesign verification failed: {e}", path.display()))?; + if !out.status.success() { + return Err(format!( + "{}: code signature verification failed (binary trust boundary)", + path.display() + )); + } + } + #[cfg(not(target_os = "macos"))] + { + use std::os::unix::fs::MetadataExt; + let md = std::fs::symlink_metadata(path) + .map_err(|e| format!("{}: cannot stat external binary: {e}", path.display()))?; + if md.file_type().is_symlink() { + return Err(format!( + "{}: external binary is a symlink; refusing to trust a symlinked binary", + path.display() + )); + } + if !md.is_file() { + return Err(format!( + "{}: external binary is not a regular file", + path.display() + )); + } + if md.uid() != 0 { + return Err(format!( + "{}: external binary owned by uid {} (expected root/0); refusing to trust", + path.display(), + md.uid() + )); + } + if md.mode() & 0o022 != 0 { + return Err(format!( + "{}: external binary is group/other writable; refusing to trust", + path.display() + )); + } + } + Ok(()) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic, unused_qualifications)] +mod tests { + use super::*; + + #[test] + #[cfg(target_os = "linux")] + fn root_owned_helpers_reject_group_and_other_write_permissions() { + use std::os::unix::fs::PermissionsExt as _; + if !rustix::process::geteuid().is_root() { + return; + } + let dir = crate::test_util::temp_dir::TestDir::new("helper-modes"); + let path = dir.join("helper"); + std::fs::write(&path, b"root-controlled helper").unwrap(); + for mode in [0o775, 0o757, 0o777] { + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode)).unwrap(); + assert!( + verify_external_binary(&path).is_err(), + "mode {mode:o} must fail" + ); + } + for mode in [0o555, 0o755] { + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode)).unwrap(); + verify_external_binary(&path).unwrap(); + } + } + + #[test] + #[cfg(target_os = "macos")] + fn verify_external_binary_accepts_codesigned_binary() { + // /usr/bin/security is Apple-signed and SIP-protected; the codesign + // verification must pass. This guards against a hypothetical SIP + // bypass or a misconfigured environment where the binary has been + // replaced. + verify_external_binary(std::path::Path::new("/usr/bin/security")) + .expect("codesigned system binary should pass verification"); + } + + #[test] + #[cfg(target_os = "macos")] + fn verify_external_binary_rejects_unsigned_file() { + // A temp file with no code signature must be rejected by codesign -v. + let dir = crate::test_util::temp_dir::TestDir::new("verify"); + let path = dir.join("fixture"); + std::fs::write(&path, b"not a signed binary").unwrap(); + let result = verify_external_binary(&path); + let _ = std::fs::remove_file(&path); + assert!( + result.is_err(), + "unsigned file should fail code signature verification" + ); + } + + #[test] + #[cfg(not(target_os = "macos"))] + fn verify_external_binary_rejects_non_root_owned() { + // Root creates a root-owned fixture, which the verifier must accept. + if rustix::process::geteuid().is_root() { + return; + } + // On Linux, a non-root-owned binary in /tmp must be rejected. + let dir = crate::test_util::temp_dir::TestDir::new("verify"); + let path = dir.join("fixture"); + std::fs::write(&path, b"fake binary").unwrap(); + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap(); + let result = verify_external_binary(&path); + let _ = std::fs::remove_file(&path); + assert!(result.is_err(), "non-root-owned binary should be rejected"); + } +} diff --git a/src/launcher.rs b/src/launcher.rs index 3a96ed7..406235d 100644 --- a/src/launcher.rs +++ b/src/launcher.rs @@ -1,377 +1,233 @@ -//! `postmaster exec` — the envelope launcher. Reads a public JSON config, -//! loads private keys, decrypts values natively (same ecies path as the -//! daemon), injects via the configured mode, and execvp's the target. -//! This file OWNS the injection boundary formerly templated as shell in -//! modules/lib.nix: values are opaque bytes end to end — no interpolation, -//! no eval, no shell. - -#![allow(missing_docs, missing_debug_implementations)] +//! Read a public launch config, load keys, decrypt inputs, and project values +//! before replacing the launcher with the target binary through `execvp`. +//! Decrypted values are injected as bytes without shell evaluation. Plaintext +//! dotenv inputs follow `dotenvy` parsing rules, including variable substitution. use std::collections::HashMap; use std::ffi::OsString; use std::fs; -use std::io::Read; use std::os::unix::ffi::OsStringExt; -use std::os::unix::fs::MetadataExt; use std::os::unix::process::CommandExt; use std::path::{Path, PathBuf}; -use zeroize::Zeroizing; +#[cfg(target_os = "linux")] +use rustix::runtime_448b8ad740e2a26f as runtime; use crate::adapter::KeyNaming; use crate::bundle::{parse_bundle, resolve_bundle}; -use crate::config::{ExecConfig, ExecMode, KeySourceSpec}; -use crate::keys::{KeyRing, resolve_all}; -use crate::server::{fetch_bytes, log}; +use crate::exec_config::{ExecConfig, ExecMode}; +use crate::key_source::load_ring; +use crate::keys::{is_private_key_var_name, resolve_all}; +use crate::monitor::{self, STOP_SIGNALS}; +use crate::ramdisk::open_verified_ramdisk_dir; +use crate::secret_files::{ + Resolved, cleanup_written, env_pairs, open_secrets_dir, prune_stale_at, write_secret_file, +}; +use crate::server::{fetch_bytes, log, read_capped}; + +/// Guard deferring termination signals across the window where plaintext +/// secret files exist on the ramdisk/tmpfs. A +/// signal landing mid-write would otherwise strand partial plaintext, so +/// the four termination signals (`STOP_SIGNALS`) are *blocked* across the +/// window. The sibling monitor is then forked — it inherits the blocked +/// mask and keeps it for life (see monitor.rs) — and the parent restores +/// the saved mask before execvp so the service starts with a clean +/// signal state. +/// +/// The monitor consumes stop signals synchronously. This guard protects +/// the write window with `block` and restores the captured mask through +/// `restore_mask` on Linux and macOS. A block failure is logged and leaves +/// that window unguarded; terminal-input callers refuse to proceed. +#[cfg(target_os = "macos")] +pub(crate) struct TerminationGuard { + /// `None` only if the block call failed (logged); restore then no-ops + /// rather than installing an empty mask that would unblock signals the + /// launcher's parent deliberately blocked — mirrors the Linux leg. + old: Option, +} -type Resolved = Vec<(String, Zeroizing>)>; +#[cfg(target_os = "macos")] +impl TerminationGuard { + pub(crate) fn block() -> Self { + Self::block_signals(&STOP_SIGNALS) + } -/// Ordered key-source selection. `credential` is skippable (no -/// $CREDENTIALS_DIRECTORY or file absent ⇒ try next source); every other -/// source is terminal: once selected, its failure fails the launcher. -// `wanted_vars` is only consumed by the macOS keychain source; on other -// targets the parameter is unused, so silence that leg's clippy warning -// without touching the signature or source-selection semantics. -#[cfg_attr(not(target_os = "macos"), allow(unused_variables))] -fn load_ring(specs: &[KeySourceSpec], wanted_vars: &[String]) -> Result { - for spec in specs { - match spec { - KeySourceSpec::Credential(name) => { - if let Some(dir) = std::env::var_os("CREDENTIALS_DIRECTORY") { - let p = Path::new(&dir).join(name); - // Use symlink_metadata instead of p.exists(): exists() - // follows symlinks, so a planted symlink at - // $CREDENTIALS_DIRECTORY/ pointing to a - // world-readable file would be silently followed. - // Reject symlinks outright (audit finding #2); the - // subsequent KeyRing::load also opens with O_NOFOLLOW - // as defense-in-depth. - match fs::symlink_metadata(&p) { - Ok(md) if md.file_type().is_symlink() => { - return Err(format!( - "{}: credential source is a symlink; refusing to follow (remove the symlink)", - p.display() - )); - } - Ok(md) if md.is_file() => return KeyRing::load(&p, KeyNaming::Env), - Ok(_) => { - return Err(format!( - "{}: credential source is not a regular file", - p.display() - )); - } - Err(_) => { /* absent: fall through to next source */ } - } - } - // absent credential: fall through to the next source - } - KeySourceSpec::File(p) => { - if p.starts_with("/nix/store") { - return Err(format!( - "{}: refusing plaintext private keys from the world-readable Nix store", - p.display() - )); - } - return KeyRing::load(p, KeyNaming::Env); + pub(crate) fn block_input() -> Self { + Self::block_signals(&[ + STOP_SIGNALS[0], + STOP_SIGNALS[1], + STOP_SIGNALS[2], + STOP_SIGNALS[3], + rustix::process::Signal::TSTP, + ]) + } + + pub(crate) fn active(&self) -> bool { + self.old.is_some() + } + + fn block_signals(signals: &[rustix::process::Signal]) -> Self { + unsafe { + // SAFETY: zeroed sigset_t is a valid empty set representation; + // all pointers are valid and outlive the calls. + let mut set: libc::sigset_t = std::mem::zeroed(); + libc::sigemptyset(&mut set); + for sig in signals { + libc::sigaddset(&mut set, sig.as_raw()); } - KeySourceSpec::Keychain(service) => { - #[cfg(target_os = "macos")] - return KeyRing::from_keychain(service, wanted_vars, KeyNaming::Env); - #[cfg(not(target_os = "macos"))] - return Err(format!( - "key source keychain({service}) is only available on macOS" - )); + let mut old: libc::sigset_t = std::mem::zeroed(); + // pthread form: correct in single- and multi-threaded processes. + if libc::pthread_sigmask(libc::SIG_BLOCK, &set, &mut old) != 0 { + // Cannot realistically fail (bad arguments are impossible + // here) — but if it ever does, log and run unguarded + // rather than silently pretend the window is protected. + log("termination-guard: pthread_sigmask failed"); + return Self { old: None }; } - KeySourceSpec::Environment => return KeyRing::from_env(KeyNaming::Env), + Self { old: Some(old) } } } - Err("no usable key source (configure keys=[…] or set DOTENV_PRIVATE_KEY*)".into()) -} - -/// Pure parser for /sbin/mount output: is `mp` mounted as HFS? -fn mount_lists_hfs(mount_out: &str, mp: &Path) -> bool { - // Strip trailing slashes so a mount point like "/foo/" matches - // "/foo" in mount output (which never includes trailing slashes). - let mp_str = mp.to_string_lossy(); - let mp_trimmed = mp_str.trim_end_matches('/'); - let needle = format!(" on {mp_trimmed} (hfs"); - mount_out.lines().any(|l| l.contains(&needle)) -} -/// Extract the device path for a mount point from `mount` output. -/// Format: `/dev/disk8 on /path (hfs, ...)` → `/dev/disk8`. -fn mount_device_for(mount_out: &str, mp: &Path) -> Option { - let mp_str = mp.to_string_lossy(); - let mp_trimmed = mp_str.trim_end_matches('/'); - let needle = format!(" on {mp_trimmed} (hfs"); - for line in mount_out.lines() { - if let Some(idx) = line.find(&needle) { - // The device is everything before " on " - let device = &line[..idx].trim(); - if !device.is_empty() { - return Some(device.to_string()); + pub(crate) fn input_pending(&self) -> Result { + // SAFETY: sigpending initializes valid storage; sigismember receives that set. + unsafe { + let mut pending: libc::sigset_t = std::mem::zeroed(); + if libc::sigpending(&mut pending) != 0 { + return Err("cannot check pending input signals".into()); } + Ok(STOP_SIGNALS + .iter() + .any(|s| libc::sigismember(&pending, s.as_raw()) == 1) + || libc::sigismember(&pending, libc::SIGTSTP) == 1) } } - None -} - -/// Verify that a device is backed by RAM (not a file-backed disk image). -/// Parses `hdiutil info` text output for the device's `image-path` -/// field and checks it starts with `ram://`. -fn device_is_ram_backed(device: &str, hdiutil_out: &str) -> bool { - // hdiutil info output structure (per image entry): - // image-path : ram://1024 - // image-type : read/write - // ... - // /dev/disk8 - // - // The device appears as a line by itself after the image properties. - // We find the device line, then scan backwards for the image-path - // field in the same image entry. - let lines: Vec<&str> = hdiutil_out.lines().collect(); - let device_line = device.trim(); - for (idx, line) in lines.iter().enumerate() { - if line.trim() == device_line { - // Scan backwards from the device line to find image-path - for prev in lines[..idx].iter().rev() { - let trimmed = prev.trim(); - if trimmed.starts_with("image-path") { - // Extract the value after "image-path : " - if let Some(colon_idx) = trimmed.find(':') { - let value = trimmed[colon_idx + 1..].trim(); - return value.starts_with("ram://"); - } - } - // If we hit another device line or a separator, this - // image entry's properties ended — stop scanning. - if trimmed.starts_with("/dev/") || trimmed.starts_with("====") { - break; - } + /// Restore the saved signal mask. The parent calls this before + /// execvp — the child must not inherit blocked termination signals. + pub(crate) fn restore_mask(&self) { + if let Some(old) = &self.old { + unsafe { + // SAFETY: restoring a previously saved valid mask. + libc::pthread_sigmask(libc::SIG_SETMASK, old, std::ptr::null_mut()); } - return false; } } - false } -/// darwin ramdisk guard (was ramdiskGuard in modules/darwin.nix): plaintext -/// lands only on the postmaster ramdisk, in a directory this user owns. -fn verify_ramdisk(mount_point: &Path, secrets_dir: &Path) -> Result<(), String> { - let out = std::process::Command::new("/sbin/mount") - .output() - .map_err(|e| format!("/sbin/mount: {e}"))?; - let text = String::from_utf8_lossy(&out.stdout); - if !mount_lists_hfs(&text, mount_point) { - return Err(format!( - "{}: not the postmaster ramdisk; refusing to write plaintext to persistent disk", - mount_point.display() - )); - } - // Verify the mount is RAM-backed, not a file-backed HFS image. - // Extract the device from mount output, then check hdiutil info - // for that device's image-path starting with ram://. - let device = mount_device_for(&text, mount_point).ok_or_else(|| { - format!( - "{}: could not determine backing device from mount output", - mount_point.display() - ) - })?; - let hdiutil_out = std::process::Command::new("/usr/bin/hdiutil") - .arg("info") - .output() - .map_err(|e| format!("hdiutil info: {e}"))?; - let hdiutil_text = String::from_utf8_lossy(&hdiutil_out.stdout); - if !device_is_ram_backed(&device, &hdiutil_text) { - return Err(format!( - "{}: mount device {device} is not RAM-backed (image-path does not start with ram://); refusing to write plaintext to a file-backed disk image", - mount_point.display() - )); - } - // Use symlink_metadata instead of metadata: if secrets_dir is itself a - // symlink to persistent disk (planted by a prior compromised launch on - // the darwin ramdisk, which persists across restarts), fs::metadata would - // follow the link and inspect the TARGET — a directory owned by the - // service user on persistent disk — and approve it. Reject symlinks - // outright so the ramdisk invariant is not bypassed. - let md = fs::symlink_metadata(secrets_dir).map_err(|e| { - format!( - "{}: {e} (is postmaster-ramdisk healthy?)", - secrets_dir.display() - ) - })?; - if md.file_type().is_symlink() { - return Err(format!( - "{}: secrets_dir is a symlink; refusing to follow — remove the symlink and ensure the directory is on the ramdisk", - secrets_dir.display() - )); - } - if !md.is_dir() || md.uid() != rustix::process::geteuid().as_raw() { - return Err(format!( - "{}: missing or not owned by this service user (is postmaster-ramdisk healthy?)", - secrets_dir.display() - )); +#[cfg(target_os = "macos")] +impl Drop for TerminationGuard { + fn drop(&mut self) { + self.restore_mask(); } - Ok(()) } -/// Resolved values → env pairs. Env values cannot hold NUL; fail closed -/// rather than truncate. -fn env_pairs(resolved: &Resolved) -> Result, String> { - let mut out = Vec::with_capacity(resolved.len()); - for (k, v) in resolved { - if v.contains(&0) { - return Err(format!( - "{k}: value contains a NUL byte; cannot be an environment variable (use files mode)" - )); - } - out.push((OsString::from(k.clone()), OsString::from_vec(v.to_vec()))); - } - Ok(out) +/// Linux leg of the guard (see the macOS docs above): same block/restore +/// contract via rustix's raw `rt_sigprocmask` — no libc FFI. +#[cfg(target_os = "linux")] +pub(crate) struct TerminationGuard { + /// `None` only if the block call failed (logged); restore then no-ops + /// rather than clobbering a mask that was never captured. + old: Option, } -/// Writes `value` to `dir.join(key)`. Invariant this enforces: plaintext -/// lands only on the mount `verify_ramdisk` already checked — a symlink -/// planted at the target path (e.g. by leftover/attacker-controlled state -/// in a per-service ramdisk dir that persists across restarts) must never -/// be followed onto persistent disk, so the open refuses symlinks -/// (`O_NOFOLLOW`) and fails closed instead. -fn write_secret_file(dir: &Path, key: &str, value: &[u8]) -> Result { - use std::io::Write; - let path = dir.join(key); - let oflags = rustix::fs::OFlags::WRONLY - | rustix::fs::OFlags::CREATE - | rustix::fs::OFlags::TRUNC - | rustix::fs::OFlags::NOFOLLOW - | rustix::fs::OFlags::CLOEXEC; - let fd = rustix::fs::open(&path, oflags, rustix::fs::Mode::from_bits_truncate(0o600)) - .map_err(|e| format!("{}: {e} (refusing to follow a symlink)", path.display()))?; - // Use fchmod on the fd (not set_permissions on the path) to eliminate a - // TOCTOU: between open(O_NOFOLLOW) and a path-based chmod, an attacker - // with directory write access could unlink the file and create a symlink - // at the same path. fchmod operates on the already-opened fd, which is - // the file we just created — no path re-resolution occurs. - rustix::fs::fchmod(&fd, rustix::fs::Mode::from_bits_truncate(0o600)) - .map_err(|e| format!("{}: fchmod: {e}", path.display()))?; - let mut f = fs::File::from(fd); - f.write_all(value) - .and_then(|()| f.flush()) - .map_err(|e| format!("{}: write: {e}", path.display()))?; - Ok(path) -} +#[cfg(target_os = "linux")] +impl TerminationGuard { + pub(crate) fn block() -> Self { + Self::block_signals(&STOP_SIGNALS) + } -/// Unlink all paths in `written` (best-effort) after a mid-loop failure so -/// stale plaintext files do not persist on the ramdisk/tmpfs. The caller -/// must only push successfully-written secret file paths here. -fn cleanup_written(written: &[PathBuf]) { - for p in written { - let _ = fs::remove_file(p); + pub(crate) fn block_input() -> Self { + Self::block_signals(&[ + STOP_SIGNALS[0], + STOP_SIGNALS[1], + STOP_SIGNALS[2], + STOP_SIGNALS[3], + rustix::process::Signal::TSTP, + ]) } -} -/// Prune stale secret files from `dir` that are not in `keep_keys`. This -/// removes plaintext files left behind by a previous launch whose config -/// has since changed (a key removed from credential_keys or a resolved key -/// set that no longer includes a prior entry). Best-effort: logs but does -/// not fail if a file cannot be removed, since the primary invariant — -/// plaintext is transient — is best served by cleaning what we can rather -/// than aborting the launch over an unrelated stale file. -fn prune_stale(dir: &Path, keep_keys: &[String]) -> Result<(), String> { - let keep: std::collections::HashSet<&str> = keep_keys.iter().map(String::as_str).collect(); - let entries = match fs::read_dir(dir) { - Ok(e) => e, - // If the directory does not exist yet, there is nothing to prune. - Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()), - Err(e) => return Err(format!("{}: prune: {e}", dir.display())), - }; - for entry in entries { - let entry = match entry { - Ok(e) => e, - Err(e) => { - log(&format!( - "{}: prune: skip unreadable entry: {e}", - dir.display() - )); - continue; - } - }; - let name = entry.file_name(); - let Some(name_str) = name.to_str() else { - continue; - }; - if keep.contains(name_str) { - continue; + pub(crate) fn active(&self) -> bool { + self.old.is_some() + } + + fn block_signals(signals: &[rustix::process::Signal]) -> Self { + let mut set = runtime::KernelSigSet::empty(); + for sig in signals { + set.insert(*sig); } - // Only unlink regular files; skip subdirectories and symlinks to - // avoid following attacker-controlled links in a shared dir. - let path = entry.path(); - match fs::symlink_metadata(&path) { - Ok(md) if md.is_file() => { - if let Err(e) = fs::remove_file(&path) { - log(&format!("{}: prune: {e}", path.display())); - } - } - Ok(md) => { - log(&format!( - "{}: prune: skipping non-file (type {:?})", - path.display(), - md.file_type() - )); - } + // SAFETY: the set holds standard termination signals and, for + // terminal input, TSTP — none reserved by any libc (glibc + // reserves 32/33, untouched). The launcher is single-threaded at + // this point (the exec path spawns no threads; worker threads + // exist only in serve mode). + match unsafe { runtime::kernel_sigprocmask(runtime::How::BLOCK, Some(&set)) } { + Ok(old) => Self { old: Some(old) }, Err(e) => { - log(&format!("{}: prune: stat: {e}", path.display())); + // rt_sigprocmask cannot realistically fail here (EINVAL/ + // EFAULT cover bad arguments, both impossible) — but if it + // ever does, log it and run unguarded rather than silently + // pretend the window is protected. + log(&format!("termination-guard: sigprocmask failed: {e}")); + Self { old: None } } } } - Ok(()) -} -/// Preflight key freshness check (audit finding #4): verify that the -/// loaded key ring can actually decrypt at least one encrypted value -/// from the env files. Catches stale keys from a previous rotation -/// cycle that are valid hex but no longer match the ciphertext. Without -/// this check, `strict: false` would silently skip undecryptable values -/// and launch the child with no secrets. -/// -/// The check scans each env file for the first `encrypted:` value and -/// attempts a test decryption. If no encrypted values exist (all -/// plaintext passthrough), the check passes trivially. -fn verify_key_freshness(resolved: &Resolved, env_files: &[PathBuf]) -> Result<(), String> { - // If we resolved at least one value, the keys are fresh enough. - // An empty resolved vec with encrypted values in the env files means - // the keys are stale (all decryptions failed under strict:false). - if !resolved.is_empty() { - return Ok(()); + pub(crate) fn input_pending(&self) -> Result { + let pending = runtime::kernel_sigpending(); + Ok(STOP_SIGNALS.iter().any(|s| pending.contains(*s)) + || pending.contains(rustix::process::Signal::TSTP)) } - // resolved is empty: check whether any env file contains encrypted - // values. If none do (all plaintext), the empty result is expected. - for env_file in env_files { - let iter = match dotenvy::from_path_iter(env_file) { - Ok(it) => it, - Err(e) => return Err(format!("{}: {e}", env_file.display())), - }; - for item in iter { - let (k, v) = match item { - Ok(p) => p, - Err(e) => return Err(format!("{}: {e}", env_file.display())), - }; - if let Some(prefix) = KeyNaming::Env.metadata_prefix() - && k.starts_with(prefix) - { - continue; - } - if v.starts_with("encrypted:") { - // Found an encrypted value but resolved is empty: the - // keys are stale and could not decrypt it. - return Err(format!( - "{}: --verify-keys failed: key ring could not decrypt {k} (stale keys from a previous rotation?)", - env_file.display() - )); - } + + /// Restore the saved signal mask (see the macOS docs). + pub(crate) fn restore_mask(&self) { + if let Some(old) = &self.old { + // SAFETY: restoring a mask previously returned by the kernel + // for this thread. + let _ = unsafe { runtime::kernel_sigprocmask(runtime::How::SETMASK, Some(old)) }; } } - // No encrypted values found: the empty resolved vec is expected. +} + +#[cfg(target_os = "linux")] +impl Drop for TerminationGuard { + fn drop(&mut self) { + self.restore_mask(); + } +} + +/// Read and deserialize an ExecConfig from a JSON file. Shared by +/// `check_config` (validate-only) and `exec` (validate + materialize). +pub fn parse_exec_config(config_path: &Path) -> Result { + let file = + fs::File::open(config_path).map_err(|e| format!("{}: {e}", config_path.display()))?; + let raw = read_capped(file, config_path)?; + serde_json::from_slice(&raw).map_err(|e| format!("{}: {e}", config_path.display())) +} + +/// Validate the public shape of an exec config without decrypting, +/// reading key material, or inspecting deployment resources. Only the +/// configuration file is read. This is the `--check` contract for CI. +pub fn check_config(config_path: &Path) -> Result<(), String> { + let cfg = parse_exec_config(config_path)?; + cfg.validate_shape() +} + +/// Preflight key freshness check: fail if any encrypted env value was +/// skipped during resolution because the key ring could not decrypt it. +/// Under `strict: false`, the failure list recorded by `resolve_all` makes +/// every skipped value visible to `--verify-keys`, including partial rotation. +/// +/// Bundle files need no scan here: `resolve_bundle` is all-or-nothing — +/// the first undecryptable entry aborts `decrypt()` regardless of +/// `strict`, so stale bundle keys already fail closed before this check +/// runs. +fn verify_key_freshness(failed: &[(String, String)]) -> Result<(), String> { + if let Some((k, _)) = failed.first() { + return Err(format!( + "--verify-keys failed: key ring could not decrypt {k} (stale keys from a previous rotation?)" + )); + } Ok(()) } @@ -395,7 +251,10 @@ fn validate_credential_keys(keys: &[String]) -> Result<(), String> { Ok(()) } -fn decrypt(cfg: &ExecConfig) -> Result { +/// Decrypt all configured inputs. Returns the resolved (name, plaintext) +/// pairs plus the `(name, error)` list of encrypted env values skipped +/// under `strict: false` (consumed by `verify_key_freshness`). +fn decrypt(cfg: &ExecConfig) -> Result<(Resolved, Vec<(String, String)>), String> { if cfg.env_files.is_empty() && cfg.bundle_files.is_empty() { return Err("exec config lists no env_files or bundle_files".into()); } @@ -408,25 +267,45 @@ fn decrypt(cfg: &ExecConfig) -> Result { for f in &cfg.bundle_files { wanted.push(KeyNaming::Bundle.key_var_for(f)?); } - let ring = load_ring(&cfg.keys, &wanted)?; + let ring = load_ring(&cfg.keys, &wanted, &cfg.required_namings())?; - // Resolve .env files (if any) via the env adapter - let mut resolved: Resolved = if cfg.env_files.is_empty() { - Vec::new() + // Resolve .env files (if any) via the env adapter. Values skipped under strict:false + // are recorded in `failed` so --verify-keys can fail closed on a partial key + // rotation. + let (mut resolved, failed): (Resolved, Vec<(String, String)>) = if cfg.env_files.is_empty() { + (Vec::new(), Vec::new()) } else { - resolve_all( + let r = resolve_all( &cfg.env_files, &ring, cfg.overload, cfg.strict, &|k| std::env::var_os(k).is_some(), KeyNaming::Env, - )? + )?; + (r.resolved, r.failed) }; - // Resolve bundle files (if any) via the bundle adapter + let mut positions: HashMap = resolved + .iter() + .enumerate() + .map(|(i, (name, _))| (name.clone(), i)) + .collect(); + // Bundle files follow env files and use the same first/last-wins contract. for bundle_path in &cfg.bundle_files { - let raw = fs::read(bundle_path).map_err(|e| format!("{}: {e}", bundle_path.display()))?; + // O_NOFOLLOW on the ciphertext open: refuse to read through a planted symlink. + let bundle_fd = rustix::fs::open( + bundle_path, + rustix::fs::OFlags::RDONLY | rustix::fs::OFlags::NOFOLLOW | rustix::fs::OFlags::CLOEXEC, + rustix::fs::Mode::empty(), + ) + .map_err(|e| { + format!( + "{}: {e} (refusing to follow a symlink)", + bundle_path.display() + ) + })?; + let raw = read_capped(fs::File::from(bundle_fd), bundle_path)?; let bundle = parse_bundle(&raw, bundle_path)?; let bundle_resolved = resolve_bundle(&bundle, &ring, bundle_path)?; for (name, value, encoding) in bundle_resolved { @@ -434,556 +313,62 @@ fn decrypt(cfg: &ExecConfig) -> Result { if !cfg.overload && std::env::var_os(&name).is_some() { continue; } - // NUL check for utf8 entries that would become env vars + // NUL check for utf8 entries that would become env vars. One rule for every + // env-bound value: NUL is a hard error, identical to the .env path in + // env_pairs — no strict-gated skip. if matches!(cfg.mode, ExecMode::Env) && encoding == crate::bundle::Encoding::Utf8 && value.contains(&0) { - if cfg.strict { - return Err(format!( - "{name}: value contains a NUL byte; cannot be an environment variable (use files mode)" - )); - } - log(&format!("non-strict: skipping {name}: NUL byte in value")); - continue; - } - resolved.push((name, value)); - } - } - - Ok(resolved) -} - -pub fn check_config(config_path: &Path) -> Result<(), String> { - let cfg = parse_exec_config(config_path)?; - cfg.validate_shape() -} - -/// `postmaster setup`: verify platform prerequisites, create keys -/// directory with correct permissions, optionally seed keychain items, -/// and validate the environment. Idempotent — skips steps that are -/// already correct. -/// -/// `--recheck`: re-run verification checks only, without creating or -/// modifying anything. Equivalent to the old `setup_recheck`. -/// -/// `--unattended`: non-interactive mode for automation. Uses defaults -/// or env vars instead of prompting. Fail closed on any missing -/// prerequisite. -/// -/// `--force`: re-seed or re-create even if the target state is already -/// present. -/// -/// `--keys-dir `: override the keys directory path. Default is -/// `postmaster cleanup`: remove all secret files from the secrets_dir -/// configured in the exec config. Intended for `ExecStopPost` in systemd -/// or equivalent lifecycle hooks. Does not decrypt — only removes files -/// that postmaster would have written. Safe to run even if the directory -/// is empty or does not exist. -pub fn cleanup(config_path: &Path) -> Result<(), String> { - let cfg = parse_exec_config(config_path)?; - let dir = cfg - .secrets_dir - .as_deref() - .ok_or("cleanup: config has no secrets_dir — nothing to clean up")?; - let entries = match fs::read_dir(dir) { - Ok(e) => e, - Err(e) if e.kind() == std::io::ErrorKind::NotFound => { - log(&format!( - "cleanup: {} does not exist; nothing to clean up", - dir.display() - )); - return Ok(()); - } - Err(e) => return Err(format!("{}: cleanup: {e}", dir.display())), - }; - let mut removed = 0_usize; - for entry in entries { - let entry = match entry { - Ok(e) => e, - Err(e) => { - log(&format!( - "{}: cleanup: skip unreadable entry: {e}", - dir.display() - )); - continue; - } - }; - let path = entry.path(); - match fs::symlink_metadata(&path) { - Ok(md) if md.is_file() => { - if let Err(e) = fs::remove_file(&path) { - log(&format!("{}: cleanup: {e}", path.display())); - } else { - removed += 1; - } - } - Ok(md) => { - log(&format!( - "{}: cleanup: skipping non-file (type {:?})", - path.display(), - md.file_type() - )); - } - Err(e) => { - log(&format!("{}: cleanup: stat: {e}", path.display())); - } - } - } - log(&format!( - "cleanup: removed {removed} file(s) from {}", - dir.display() - )); - Ok(()) -} - -/// Default keys directory path: `/var/lib/postmaster` on Linux, -/// `~/Library/Application Support/postmaster` on macOS. -pub fn setup( - config_path: &Path, - recheck: bool, - unattended: bool, - force: bool, - keys_dir_override: Option, -) -> Result<(), String> { - let cfg = parse_exec_config(config_path)?; - cfg.validate_shape()?; - - // Build the wanted key variable list from both env and bundle files - let mut wanted: Vec = Vec::new(); - for f in &cfg.env_files { - wanted.push(KeyNaming::Env.key_var_for(f)?); - } - for f in &cfg.bundle_files { - wanted.push(KeyNaming::Bundle.key_var_for(f)?); - } - - // Step 1: Verify platform prerequisites - verify_platform_prerequisites(&cfg, unattended)?; - - if recheck { - // --recheck: verification only, no creation or modification - return verify_key_sources(&cfg, &wanted); - } - - // Step 2: Create or verify keys directory - let keys_dir = keys_dir_override.unwrap_or_else(default_keys_dir); - ensure_keys_dir(&keys_dir, force)?; - - // Step 3: Verify or create key files for file-source keys - for spec in &cfg.keys { - if let KeySourceSpec::File(path) = spec { - ensure_keys_file(path, force, unattended)?; - } - } - - // Step 4: Verify or seed keychain items (macOS only) - #[cfg(target_os = "macos")] - for spec in &cfg.keys { - if let KeySourceSpec::Keychain(service) = spec { - ensure_keychain_items(service, &wanted, force, unattended)?; - } - } - - // Step 5: Verify the full environment (same as --recheck) - verify_key_sources(&cfg, &wanted)?; - - log(&format!( - "setup: complete — keys dir {}, {} key source(s) verified", - keys_dir.display(), - cfg.keys.len() - )); - Ok(()) -} - -/// Default keys directory path: `/var/lib/postmaster` on Linux, -/// `~/Library/Application Support/postmaster` on macOS. -fn default_keys_dir() -> PathBuf { - #[cfg(target_os = "macos")] - { - if let Some(home) = std::env::var_os("HOME") { - return PathBuf::from(home) - .join("Library") - .join("Application Support") - .join("postmaster"); - } - } - PathBuf::from("/var/lib/postmaster") -} - -/// Verify platform prerequisites: codesign check on macOS, root-owned -/// binary check on Linux. Fails closed in unattended mode if the -/// external binary can't be verified. -fn verify_platform_prerequisites(cfg: &ExecConfig, _unattended: bool) -> Result<(), String> { - // Only check if keychain source is configured (the only source that - // invokes an external binary) - let has_keychain = cfg - .keys - .iter() - .any(|k| matches!(k, KeySourceSpec::Keychain(_))); - if !has_keychain { - return Ok(()); - } - - #[cfg(target_os = "macos")] - { - // Verify /usr/bin/security code signature - crate::keys::verify_external_binary(Path::new("/usr/bin/security")) - .map_err(|e| format!("platform prerequisite: {e}"))?; - log("setup: platform prerequisite verified (codesign /usr/bin/security)"); - } - - #[cfg(not(target_os = "macos"))] - { - let _ = unattended; - log("setup: no platform-specific prerequisites on this OS"); - } - - Ok(()) -} - -/// Create the keys directory with 0700 permissions if it doesn't exist. -/// If it exists, verify permissions and ownership are correct. Idempotent -/// — skips if already correct unless `force` is true. -fn ensure_keys_dir(keys_dir: &Path, _force: bool) -> Result<(), String> { - if keys_dir.exists() { - // Verify it's a directory, not a symlink - let md = - fs::symlink_metadata(keys_dir).map_err(|e| format!("{}: {e}", keys_dir.display()))?; - if md.is_symlink() { - return Err(format!( - "{}: refusing to use a symlink as keys directory", - keys_dir.display() - )); - } - if !md.is_dir() { - return Err(format!( - "{}: exists but is not a directory", - keys_dir.display() - )); - } - // Verify permissions: 0700 (rwx------) - use std::os::unix::fs::PermissionsExt; - let mode = md.permissions().mode(); - if mode & 0o077 != 0 { - // Fix permissions if we can - fs::set_permissions(keys_dir, fs::Permissions::from_mode(0o700)) - .map_err(|e| format!("{}: cannot fix permissions: {e}", keys_dir.display()))?; - log(&format!( - "{}: permissions corrected to 0700", - keys_dir.display() - )); - } - log(&format!("{}: keys directory verified", keys_dir.display())); - return Ok(()); - } - - // Create the directory with 0700 - fs::create_dir_all(keys_dir) - .map_err(|e| format!("{}: cannot create keys directory: {e}", keys_dir.display()))?; - use std::os::unix::fs::PermissionsExt; - fs::set_permissions(keys_dir, fs::Permissions::from_mode(0o700)) - .map_err(|e| format!("{}: cannot set permissions: {e}", keys_dir.display()))?; - log(&format!( - "{}: keys directory created with 0700", - keys_dir.display() - )); - Ok(()) -} - -/// Verify a keys file exists with correct permissions (0600, owned by -/// euid). If the file doesn't exist, in interactive mode, prompt the -/// operator to create it. In unattended mode, fail closed. If the file -/// exists but has wrong permissions, fix them. -#[allow(clippy::print_stderr)] -fn ensure_keys_file(path: &Path, _force: bool, unattended: bool) -> Result<(), String> { - if path.exists() { - // Verify permissions and ownership (same checks as setup_recheck) - let oflags = - rustix::fs::OFlags::RDONLY | rustix::fs::OFlags::NOFOLLOW | rustix::fs::OFlags::CLOEXEC; - let fd = rustix::fs::open(path, oflags, rustix::fs::Mode::empty()) - .map_err(|e| format!("{}: {e} (refusing to follow a symlink)", path.display()))?; - let stat = rustix::fs::fstat(&fd).map_err(|e| format!("{}: fstat: {e}", path.display()))?; - let mode = rustix::fs::Mode::from_bits_truncate(stat.st_mode); - if mode.intersects(rustix::fs::Mode::RWXG | rustix::fs::Mode::RWXO) { - // Fix permissions - rustix::fs::fchmod(&fd, rustix::fs::Mode::RUSR | rustix::fs::Mode::WUSR) - .map_err(|e| format!("{}: cannot fix permissions: {e}", path.display()))?; - log(&format!( - "{}: permissions corrected to 0600", - path.display() - )); - } - let euid = rustix::process::geteuid().as_raw(); - if stat.st_uid != euid { - return Err(format!( - "{}: owned by uid {} but postmaster euid is {euid} (cannot fix ownership automatically)", - path.display(), - stat.st_uid - )); - } - log(&format!("{}: keys file verified", path.display())); - return Ok(()); - } - - // File doesn't exist - if unattended { - return Err(format!( - "{}: keys file not found (unattended mode — cannot prompt; create the file manually before running setup)", - path.display() - )); - } - - // Interactive: prompt the operator - eprintln!("{}: keys file not found.", path.display()); - eprintln!( - "Create it now? You will need to paste the key contents (DOTENV_PRIVATE_KEY=<64-hex>...). [y/N] " - ); - let mut input = String::new(); - if std::io::stdin().read_line(&mut input).is_err() { - return Err(format!("{}: cannot read input", path.display())); - } - if !input.trim().eq_ignore_ascii_case("y") { - return Err(format!( - "{}: operator declined to create keys file", - path.display() - )); - } - - eprintln!("Paste the keys file contents (Ctrl+D to finish):"); - let mut contents = String::new(); - if std::io::stdin().read_to_string(&mut contents).is_err() { - return Err(format!("{}: cannot read key contents", path.display())); - } - - // Write the file with 0600 - use std::os::unix::fs::OpenOptionsExt; - let mut file = fs::OpenOptions::new() - .write(true) - .create(true) - .truncate(true) - .mode(0o600) - .open(path) - .map_err(|e| format!("{}: cannot create: {e}", path.display()))?; - use std::io::Write; - file.write_all(contents.as_bytes()) - .map_err(|e| format!("{}: cannot write: {e}", path.display()))?; - log(&format!("{}: keys file created with 0600", path.display())); - Ok(()) -} - -/// Verify keychain items exist for the wanted key variables. If they -/// don't exist and we're in interactive mode, offer to seed them. -/// On macOS only. -#[cfg(target_os = "macos")] -#[allow(clippy::print_stderr)] -fn ensure_keychain_items( - service: &str, - wanted: &[String], - force: bool, - unattended: bool, -) -> Result<(), String> { - let mut missing: Vec<&str> = Vec::new(); - for var in wanted { - let out = std::process::Command::new("/usr/bin/security") - .args(["find-generic-password", "-s", service, "-a", var, "-w"]) - .output() - .map_err(|e| format!("security: {e}"))?; - if !out.status.success() { - missing.push(var); - } - } - - if missing.is_empty() && !force { - log(&format!( - "keychain {service}: all {wanted_len} item(s) verified", - wanted_len = wanted.len() - )); - return Ok(()); - } - - if unattended && !missing.is_empty() { - return Err(format!( - "keychain {service}: {missing_len} item(s) missing (unattended mode — cannot prompt)", - missing_len = missing.len() - )); - } - - // Interactive: offer to seed missing items - if !missing.is_empty() { - eprintln!( - "keychain {service}: missing items for: {}", - missing.join(", ") - ); - eprintln!("Seed them now? You will need to paste each key value. [y/N] "); - let mut input = String::new(); - if std::io::stdin().read_line(&mut input).is_err() { - return Err("cannot read input".into()); - } - if !input.trim().eq_ignore_ascii_case("y") { - return Err(format!( - "keychain {service}: operator declined to seed missing items" - )); - } - - for var in &missing { - eprint!("Paste value for {var}: "); - let mut value = String::new(); - if std::io::stdin().read_line(&mut value).is_err() { - return Err(format!("cannot read value for {var}")); - } - let value = value.trim(); - if value.is_empty() { - return Err(format!("{var}: empty value, refusing to seed")); - } - let out = std::process::Command::new("/usr/bin/security") - .args([ - "add-generic-password", - "-s", - service, - "-a", - var, - "-w", - value, - ]) - .output() - .map_err(|e| format!("security: {e}"))?; - if !out.status.success() { return Err(format!( - "keychain {service}: failed to seed {var}: {}", - String::from_utf8_lossy(&out.stderr) + "{name}: value contains a NUL byte; cannot be an environment variable (use files mode)" )); } - log(&format!("keychain {service}: seeded {var}")); - } - } - - Ok(()) -} - -/// Verify that all configured key sources are accessible. This is the -/// `--recheck` path — same as the old `setup_recheck` function. -fn verify_key_sources(cfg: &ExecConfig, wanted: &[String]) -> Result<(), String> { - let mut checked = 0_u32; - let mut found = 0_u32; - - for spec in &cfg.keys { - match spec { - KeySourceSpec::Credential(name) => { - checked += 1; - let dir = std::env::var_os("CREDENTIALS_DIRECTORY") - .ok_or("$CREDENTIALS_DIRECTORY is not set")?; - let p = Path::new(&dir).join(name); - if !p.exists() { - return Err(format!( - "{}: credential source not found under $CREDENTIALS_DIRECTORY", - p.display() - )); - } - found += 1; - } - KeySourceSpec::File(path) => { - checked += 1; - if path.starts_with("/nix/store") { - return Err(format!( - "{}: refusing plaintext private keys from the world-readable Nix store", - path.display() - )); - } - let oflags = rustix::fs::OFlags::RDONLY - | rustix::fs::OFlags::NOFOLLOW - | rustix::fs::OFlags::CLOEXEC; - let fd = - rustix::fs::open(path, oflags, rustix::fs::Mode::empty()).map_err(|e| { - format!("{}: {e} (refusing to follow a symlink)", path.display()) - })?; - let stat = rustix::fs::fstat(&fd) - .map_err(|e| format!("{}: fstat: {e}", path.display()))?; - let mode = rustix::fs::Mode::from_bits_truncate(stat.st_mode); - if mode.intersects(rustix::fs::Mode::RWXG | rustix::fs::Mode::RWXO) { - return Err(format!( - "{}: permissions {:#o} are group/world accessible; expected 0400 or 0600", - path.display(), - stat.st_mode - )); - } - let euid = rustix::process::geteuid().as_raw(); - if stat.st_uid != euid { - return Err(format!( - "{}: owned by uid {} but postmaster euid is {euid}", - path.display(), - stat.st_uid - )); + if let Some(&i) = positions.get(&name) { + if cfg.overload { + resolved[i].1 = value; } - found += 1; - } - KeySourceSpec::Keychain(service) => { - checked += 1; - #[cfg(target_os = "macos")] - { - for var in wanted { - let out = std::process::Command::new("/usr/bin/security") - .args(["find-generic-password", "-s", service, "-a", var, "-w"]) - .output() - .map_err(|e| format!("security: {e}"))?; - if !out.status.success() { - return Err(format!( - "keychain {service}: no item for account {var} (fail closed)" - )); - } - } - found += 1; - } - #[cfg(not(target_os = "macos"))] - { - let _ = service; - return Err("keychain source is only available on macOS".into()); - } - } - KeySourceSpec::Environment => { - checked += 1; - let env_prefix = KeyNaming::Env.key_prefix(); - let bundle_prefix = KeyNaming::Bundle.key_prefix(); - let has_key = std::env::vars() - .any(|(k, _)| k.starts_with(env_prefix) || k.starts_with(bundle_prefix)); - if !has_key { - return Err(format!( - "environment: no {env_prefix}* or {bundle_prefix}* variables set" - )); - } - found += 1; + } else { + positions.insert(name.clone(), resolved.len()); + resolved.push((name, value)); } } } - if checked == 0 { - return Err("no key sources configured (configure keys=[…])".into()); - } - - log(&format!( - "setup: {found}/{checked} key source(s) verified — environment ready" - )); - Ok(()) -} - -/// Read and deserialize an ExecConfig from a JSON file. Shared by -/// `check_config` (validate-only) and `exec` (validate + materialize). -fn parse_exec_config(config_path: &Path) -> Result { - let raw = fs::read(config_path).map_err(|e| format!("{}: {e}", config_path.display()))?; - serde_json::from_slice(&raw).map_err(|e| format!("{}: {e}", config_path.display())) + Ok((resolved, failed)) } +/// Decrypt configured secret inputs, inject them into the child +/// context, and `execvp` the target binary. The process image is +/// replaced — this function never returns on success. pub fn exec(config_path: &Path, argv: &[String], verify_keys: bool) -> Result<(), String> { let cfg = parse_exec_config(config_path)?; cfg.validate_shape()?; + let program = argv.first().ok_or("exec: empty argv")?; + // Defer termination signals until the fork/exec below, so a signal landing + // mid-write can't strand plaintext on disk (see TerminationGuard docs). The + // fork-child monitor inherits the blocked mask and keeps it for life; the parent + // restores the saved mask before execvp. + let sig_guard = TerminationGuard::block(); let mut extra: Vec<(OsString, OsString)> = Vec::new(); + // Names of plaintext files written beneath the pinned secrets-dir fd, tracked + // across the match so the failure paths (and the monitor, post-fork) can unlink + // them fd-relative. + let mut written: Vec = Vec::new(); + // The pinned secrets-dir fd (Files / Credentials-fetch modes only). Opened ONCE + // with O_DIRECTORY|O_NOFOLLOW|O_RDONLY|CLOEXEC and kept until after the + // exec-failure cleanup, so every write and every cleanup unlink is relative to the + // same pinned inode. Across the fork the monitor inherits the fd (CLOEXEC fires + // only on exec, which the monitor never performs) and holds it for the service's + // lifetime. + let mut secrets_dir_fd: Option = None; match cfg.mode { ExecMode::Env => { - let resolved = decrypt(&cfg)?; + let (resolved, failed) = decrypt(&cfg)?; if verify_keys { - verify_key_freshness(&resolved, &cfg.env_files)?; + verify_key_freshness(&failed)?; } extra = env_pairs(&resolved)?; // resolved (Zeroizing> values) dropped here — @@ -997,56 +382,45 @@ pub fn exec(config_path: &Path, argv: &[String], verify_keys: bool) -> Result<() .secrets_dir .as_deref() .ok_or("files mode requires secrets_dir")?; - match &cfg.verify_ramdisk { - Some(mp) => verify_ramdisk(mp, dir)?, - None => { - // Defense-in-depth: use symlink_metadata to reject a - // symlinked secrets_dir even on Linux where - // verify_ramdisk is not used. - let md = - fs::symlink_metadata(dir).map_err(|e| format!("{}: {e}", dir.display()))?; - if md.file_type().is_symlink() { - return Err(format!( - "{}: secrets_dir is a symlink; refusing to write plaintext through a symlink", - dir.display() - )); - } - if !md.is_dir() { - return Err(format!("{}: not a directory", dir.display())); - } - } - } - let resolved = decrypt(&cfg)?; + let dir_fd = match &cfg.verify_ramdisk { + Some(mp) => open_verified_ramdisk_dir(mp, dir)?, + None => open_secrets_dir(dir).map_err(|e| { + format!("{}: {e} (refusing to follow a symlink)", dir.display()) + })?, + }; + let projected_dir = crate::secret_files::validate_projection(&dir_fd, dir)?; + let dir = projected_dir.as_path(); + let (resolved, failed) = decrypt(&cfg)?; if verify_keys { - verify_key_freshness(&resolved, &cfg.env_files)?; + verify_key_freshness(&failed)?; } // Prune stale secret files from a prior launch before writing new ones. let keep_keys: Vec = resolved.iter().map(|(k, _)| k.clone()).collect(); - prune_stale(dir, &keep_keys)?; - let mut written: Vec = Vec::with_capacity(resolved.len()); + prune_stale_at(&dir_fd, dir, &keep_keys)?; + written.reserve(resolved.len()); for (k, v) in &resolved { - let path = match write_secret_file(dir, k, v) { + let path = match write_secret_file(&dir_fd, dir, k, v) { Ok(p) => p, Err(e) => { - cleanup_written(&written); + cleanup_written(&dir_fd, &written); return Err(e); } }; - written.push(path.clone()); + written.push(k.clone()); extra.push((OsString::from(format!("{k}_FILE")), path.into_os_string())); if cfg.passthrough.iter().any(|p| p == k) { if v.contains(&0) { - cleanup_written(&written); + cleanup_written(&dir_fd, &written); return Err(format!("{k}: passthrough value contains NUL")); } extra.push((OsString::from(k.clone()), OsString::from_vec(v.to_vec()))); } } // resolved (Zeroizing> values) dropped here — - // decrypted values zeroized before execvp. Only file paths - // (extra: OsString pairs) survive to execvp, not the - // plaintext values themselves. + // decrypted values zeroized before execvp. File pointers and + // any passthrough plaintext remain in extra for the child. drop(resolved); + secrets_dir_fd = Some(dir_fd); } ExecMode::Credentials => { if cfg.credential_keys.is_empty() { @@ -1057,7 +431,7 @@ pub fn exec(config_path: &Path, argv: &[String], verify_keys: bool) -> Result<() // systemd path: pid 1 already materialized the credentials. let dir = std::env::var_os("CREDENTIALS_DIRECTORY") .ok_or("postmaster credentials expected but CREDENTIALS_DIRECTORY is unset")?; - let dir = PathBuf::from(dir); + let dir = crate::secret_files::validate_directory_path(&PathBuf::from(dir))?; for k in &cfg.credential_keys { extra.push(( OsString::from(format!("{k}_FILE")), @@ -1065,18 +439,23 @@ pub fn exec(config_path: &Path, argv: &[String], verify_keys: bool) -> Result<() )); } } else { - // launchd path: pull each key from postmaster ourselves. + // Local socket path, normally used with launchd. let dir = cfg .secrets_dir .as_deref() .ok_or("credentials(fetch) mode requires secrets_dir")?; - if let Some(mp) = &cfg.verify_ramdisk { - verify_ramdisk(mp, dir)?; - } + let dir_fd = match &cfg.verify_ramdisk { + Some(mp) => open_verified_ramdisk_dir(mp, dir)?, + None => open_secrets_dir(dir).map_err(|e| { + format!("{}: {e} (refusing to follow a symlink)", dir.display()) + })?, + }; + let projected_dir = crate::secret_files::validate_projection(&dir_fd, dir)?; + let dir = projected_dir.as_path(); let sockets: &HashMap = &cfg.sockets; // Prune stale credential files from a prior launch. - prune_stale(dir, &cfg.credential_keys)?; - let mut written: Vec = Vec::with_capacity(cfg.credential_keys.len()); + prune_stale_at(&dir_fd, dir, &cfg.credential_keys)?; + written.reserve(cfg.credential_keys.len()); for k in &cfg.credential_keys { let sock = sockets .get(k) @@ -1084,33 +463,108 @@ pub fn exec(config_path: &Path, argv: &[String], verify_keys: bool) -> Result<() let bytes = match fetch_bytes(sock) { Ok(b) => b, Err(e) => { - cleanup_written(&written); + cleanup_written(&dir_fd, &written); return Err(e); } }; - let path = match write_secret_file(dir, k, &bytes) { + let path = match write_secret_file(&dir_fd, dir, k, &bytes) { Ok(p) => p, Err(e) => { - cleanup_written(&written); + cleanup_written(&dir_fd, &written); return Err(e); } }; - written.push(path.clone()); + written.push(k.clone()); extra.push((OsString::from(format!("{k}_FILE")), path.into_os_string())); } extra.push(( OsString::from("CREDENTIALS_DIRECTORY"), dir.as_os_str().to_os_string(), )); + secrets_dir_fd = Some(dir_fd); } } } - let program = argv.first().ok_or("exec: empty argv")?; - let err = std::process::Command::new(program) - .args(&argv[1..]) - .envs(extra) - .exec(); // only returns on failure + // Zeroization is complete at this point (the key ring dropped inside + // decrypt(); `resolved` dropped at the end of each arm above): fork + // the sibling monitor BEFORE exec. The fork-child keeps the guard's + // blocked mask for life and supervises this process — stop-signal + // forwarding, bounded grace, SIGKILL escalation, and plaintext cleanup + // on every service-death path (see monitor.rs). The parent execs the service, so + // MainPID is unchanged. The monitor runs for ALL exec launches, + // including env mode (uniform semantics; its cleanup is a no-op + // there). The pid is captured pre-fork: post-fork the parent IS the + // service-to-be, so the monitor needs no racy getppid. + let service_pid = rustix::process::getpid(); + // SAFETY: fork(2) in a single-threaded process (the exec path spawns + // no threads; the daemon's worker threads exist only in serve mode). + // The fork-child first SCRUBS the inherited `extra` env pairs in + // place (monitor::wipe_pair: zeroize, then drop — destructors and + // free() in the child), then executes only monitor::run's + // async-signal-safe syscall set (no allocation, no stdio locks, no + // destructors — documented in monitor.rs) and exits via + // _exit/exit_group. The scrub's free()s are sound here because the + // production fork parent is single-threaded at fork, so no malloc + // lock can be held by another thread; under `cargo test` + // (multithreaded) test children fork with no `extra` to scrub. + // rustix deliberately has no fork wrapper; on Linux this is the one + // libc FFI call on the exec path, flagged in + // docs/src/unsafe-code/monitor.md. + match unsafe { libc::fork() } { + -1 => { + // No monitor means no stop semantics and no cleanup on + // abnormal death: fail closed like an exec failure rather + // than launch unsupervised. + if let Some(dir_fd) = &secrets_dir_fd { + cleanup_written(dir_fd, &written); + } + let err = std::io::Error::last_os_error(); + log(&format!("exec {program}: fork: {err}")); + return Err(format!("exec {program}: fork: {err}")); + } + 0 => { + // Fork-child = the monitor (never returns). sig_guard is + // deliberately NOT dropped here: monitor::run diverges + // (`-> !`) and the _exit path runs no destructors, so the + // termination mask stays blocked for the monitor's life + // (run() re-asserts the block regardless). The inherited + // `extra` env pairs are SCRUBBED first — they hold plaintext + // values in env mode (and files-mode passthrough), and + // free() alone would leave the bytes in the monitor's + // mapped pages for its whole life (threat model: monitor + // inherited heap). + for (k, v) in extra { + drop(monitor::wipe_pair(k, v)); + } + monitor::run(service_pid, secrets_dir_fd, written); + } + _ => {} + } + // Parent only from here (the fork-child diverged). Restore the + // pre-guard signal mask so the service starts with a clean signal + // state, then exec the service. + sig_guard.restore_mask(); + let mut cmd = std::process::Command::new(program); + cmd.args(&argv[1..]).envs(extra); + // Remove after projection so resolved values cannot reintroduce private-key variables. + let private_key_names: Vec<_> = std::env::vars_os() + .map(|(name, _)| name) + .chain(cmd.get_envs().map(|(name, _)| name.to_os_string())) + .filter(|name| name.to_str().is_some_and(is_private_key_var_name)) + .collect(); + for name in private_key_names { + cmd.env_remove(name); + } + let err = cmd.exec(); // only returns on failure + // execvp failed: the process image was NOT replaced, so any plaintext secret files + // written above would otherwise persist (the macOS ramdisk survives process death). + // Remove them before returning the error. The monitor watching this process fires + // on the imminent exit and cleans again — unlinkat of already-removed names is a + // no-op. + if let Some(dir_fd) = &secrets_dir_fd { + cleanup_written(dir_fd, &written); + } log(&format!("exec {program}: {err}")); Err(format!("exec {program}: {err}")) } @@ -1120,69 +574,6 @@ pub fn exec(config_path: &Path, argv: &[String], verify_keys: bool) -> Result<() mod tests { use super::*; - #[test] - fn mount_guard_parses_mount_output() { - let out = "/dev/disk3 on / (apfs, local)\n/dev/disk7 on /private/var/run/postmaster (hfs, local, nodev, nosuid, noexec)\n"; - assert!(mount_lists_hfs( - out, - Path::new("/private/var/run/postmaster") - )); - assert!(!mount_lists_hfs(out, Path::new("/private/var/run/other"))); - assert!(!mount_lists_hfs("/dev/disk3 on / (apfs)\n", Path::new("/"))); - } - - #[test] - fn mount_device_for_extracts_device() { - let out = "/dev/disk3 on / (apfs, local)\n/dev/disk7 on /private/var/run/postmaster (hfs, local, nodev, nosuid, noexec)\n"; - assert_eq!( - mount_device_for(out, Path::new("/private/var/run/postmaster")), - Some("/dev/disk7".to_string()) - ); - assert_eq!(mount_device_for(out, Path::new("/nonexistent")), None); - } - - #[test] - fn device_is_ram_backed_detects_ram_prefix() { - let hdiutil = "\ -framework : 683.100.3 -driver : 683.100.3 -================================================ -image-path : ram://1024 -shadow-path : -icon-path : /System/Library/PrivateFrameworks/DiskImages.framework/Resources/CDiskImage.icns -image-type : read/write -system-image : false -blockcount : 1024 -blocksize : 512 -writeable : TRUE -autodiskmount : false -removable : TRUE ---\nframework name : DiskImages -/dev/disk8 -"; - assert!(device_is_ram_backed("/dev/disk8", hdiutil)); - - let hdiutil_file = "\ -================================================ -image-path : /Users/user/image.dmg -shadow-path : -image-type : read/write -/dev/disk9 -"; - assert!(!device_is_ram_backed("/dev/disk9", hdiutil_file)); - - // Device not in hdiutil output at all - assert!(!device_is_ram_backed("/dev/disk99", hdiutil)); - } - - #[test] - fn env_pairs_rejects_interior_nul() { - let ok = vec![("A".to_string(), Zeroizing::new(b"x\ny".to_vec()))]; - assert_eq!(env_pairs(&ok).unwrap().len(), 1); - let bad = vec![("A".to_string(), Zeroizing::new(b"x\0y".to_vec()))]; - assert!(env_pairs(&bad).unwrap_err().contains("NUL")); - } - #[test] fn validate_credential_keys_accepts_identifiers() { assert!(validate_credential_keys(&["DB_URL".to_string()]).is_ok()); @@ -1199,50 +590,20 @@ image-type : read/write } } - fn tdir(tag: &str) -> PathBuf { - let d = std::env::temp_dir().join(format!("pm-launcher-{tag}-{}", std::process::id())); - let _ = fs::remove_dir_all(&d); - fs::create_dir_all(&d).unwrap(); - d - } - - #[test] - fn write_secret_file_refuses_symlink() { - let dir = tdir("symlink"); - // A persistent-disk target that must never receive the plaintext. - let real_target = dir.join("real-target"); - fs::write(&real_target, b"untouched").unwrap(); - // Attacker-planted symlink at the path write_secret_file will target. - let link_path = dir.join("KEY"); - std::os::unix::fs::symlink(&real_target, &link_path).unwrap(); - - let result = write_secret_file(&dir, "KEY", b"attacker-controlled-plaintext"); - - assert!( - result.is_err(), - "write_secret_file must refuse to follow a symlink at the target path" - ); - assert_eq!( - fs::read(&real_target).unwrap(), - b"untouched", - "the symlink's target file must not be written to" - ); - } - #[test] fn exec_rejects_empty_argv_instead_of_panicking() { use std::os::unix::fs::PermissionsExt; // A config that resolves cleanly in "env" mode (no ramdisk/creds // machinery involved) so the empty-argv guard is what's exercised, // not an earlier, unrelated failure. - let d = tdir("emptyargv"); + let d = crate::test_util::temp_dir::TestDir::new("launcher"); let keys_path = d.join(".env.keys"); fs::write( &keys_path, format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32)), ) .unwrap(); - // KeyRing::load enforces 0600-or-stricter (audit finding #1). + // KeyRing::load enforces 0600-or-stricter. fs::set_permissions(&keys_path, fs::Permissions::from_mode(0o600)).unwrap(); let env_path = d.join(".env"); fs::write(&env_path, "A=hello\n").unwrap(); @@ -1260,235 +621,4 @@ image-type : read/write let err = exec(&cfg_path, &[], false).unwrap_err(); assert!(err.contains("empty argv"), "{err}"); } - - #[test] - fn prune_stale_removes_unconfigured_files() { - let dir = tdir("prune"); - // Simulate a previous launch that wrote KEY_A and KEY_B. - fs::write(dir.join("KEY_A"), b"old-a").unwrap(); - fs::write(dir.join("KEY_B"), b"old-b").unwrap(); - - // New config only keeps KEY_A; KEY_B should be pruned. - prune_stale(&dir, &["KEY_A".to_string()]).unwrap(); - - assert!(dir.join("KEY_A").exists(), "KEY_A should survive prune"); - assert!(!dir.join("KEY_B").exists(), "KEY_B should be pruned"); - } - - #[test] - fn prune_stale_skips_non_files_and_missing_dir() { - let dir = tdir("prune-nonfile"); - // A subdirectory should be skipped, not unlinked. - fs::create_dir(dir.join("subdir")).unwrap(); - // A file that is kept should survive. - fs::write(dir.join("KEEP_ME"), b"data").unwrap(); - - prune_stale(&dir, &["KEEP_ME".to_string()]).unwrap(); - assert!(dir.join("KEEP_ME").exists()); - assert!(dir.join("subdir").is_dir(), "subdir should not be removed"); - - // Non-existent directory: no error, nothing to prune. - let ghost = dir.join("does-not-exist"); - assert!(prune_stale(&ghost, &["X".to_string()]).is_ok()); - } - - #[test] - fn cleanup_written_unlinks_files() { - let dir = tdir("cleanup"); - let f1 = dir.join("A"); - let f2 = dir.join("B"); - fs::write(&f1, b"secret-a").unwrap(); - fs::write(&f2, b"secret-b").unwrap(); - - cleanup_written(&[f1.clone(), f2.clone()]); - - assert!(!f1.exists(), "cleanup should unlink f1"); - assert!(!f2.exists(), "cleanup should unlink f2"); - } - - #[test] - fn cleanup_removes_all_files_from_secrets_dir() { - let dir = tdir("cleanup-subcmd"); - fs::write(dir.join("KEY_A"), b"secret-a").unwrap(); - fs::write(dir.join("KEY_B"), b"secret-b").unwrap(); - fs::create_dir(dir.join("subdir")).unwrap(); - - let cfg_path = dir.join("exec.json"); - fs::write( - &cfg_path, - format!( - r#"{{"mode":"files","keys":["environment"],"env_files":["/nonexistent"],"secrets_dir":"{}"}}"#, - dir.display() - ), - ) - .unwrap(); - - cleanup(&cfg_path).unwrap(); - - assert!(!dir.join("KEY_A").exists(), "KEY_A should be removed"); - assert!(!dir.join("KEY_B").exists(), "KEY_B should be removed"); - assert!(dir.join("subdir").exists(), "subdir should be preserved"); - } - - #[test] - fn cleanup_nonexistent_dir_is_ok() { - let dir = tdir("cleanup-missing"); - let cfg_path = dir.join("exec.json"); - fs::write( - &cfg_path, - format!( - r#"{{"mode":"files","keys":["environment"],"env_files":["/nonexistent"],"secrets_dir":"{}/no-such-dir"}}"#, - dir.display() - ), - ) - .unwrap(); - - assert!(cleanup(&cfg_path).is_ok()); - } - - #[test] - fn load_ring_credential_is_skippable() { - // credential source with no CREDENTIALS_DIRECTORY set should fall - // through to the next source. Here the next source is "environment", - // which is terminal and will fail closed (no DOTENV_PRIVATE_KEY* - // vars in the test runner). The error must be from the environment - // source, not from the credential source. - // - // SAFETY: set_var/remove_var are unsafe on edition 2024 (not - // thread-safe). This test does not spawn threads. - unsafe { - std::env::remove_var("CREDENTIALS_DIRECTORY"); - } - let specs = vec![ - KeySourceSpec::Credential("nonexistent".to_string()), - KeySourceSpec::Environment, - ]; - let err = load_ring(&specs, &[]).unwrap_err(); - // The error should come from the environment source (terminal), - // proving credential fell through rather than erroring. - assert!( - err.contains("environment:") || err.contains("no usable key source"), - "credential should be skippable; got: {err}" - ); - } - - #[test] - fn load_ring_credential_rejects_symlink() { - // Audit finding #2: a symlink planted at - // $CREDENTIALS_DIRECTORY/ must be rejected, not followed. - use std::os::unix::fs::PermissionsExt; - let d = tdir("cred-symlink"); - let real = d.join("real-keys"); - fs::write(&real, format!("DOTENV_PRIVATE_KEY={}\n", "11".repeat(32))).unwrap(); - fs::set_permissions(&real, fs::Permissions::from_mode(0o600)).unwrap(); - let cred_dir = d.join("creds"); - fs::create_dir_all(&cred_dir).unwrap(); - let link = cred_dir.join("dotenv-private-key"); - std::os::unix::fs::symlink(&real, &link).unwrap(); - - // SAFETY: set_var/remove_var are unsafe on edition 2024 (not - // thread-safe). This test does not spawn threads. - unsafe { - std::env::set_var("CREDENTIALS_DIRECTORY", &cred_dir); - } - let specs = vec![KeySourceSpec::Credential("dotenv-private-key".to_string())]; - let err = load_ring(&specs, &[]).unwrap_err(); - unsafe { - std::env::remove_var("CREDENTIALS_DIRECTORY"); - } - assert!( - err.contains("symlink"), - "credential symlink should be rejected; got: {err}" - ); - } - - #[test] - fn load_ring_credential_rejects_non_file() { - // A directory as a credential source name should be rejected, - // not silently skipped or treated as a file. - let d = tdir("cred-dir"); - let cred_dir = d.join("creds"); - fs::create_dir_all(&cred_dir).unwrap(); - let sub = cred_dir.join("subdir"); - fs::create_dir_all(&sub).unwrap(); - - // SAFETY: set_var/remove_var are unsafe on edition 2024 (not - // thread-safe). This test does not spawn threads. - unsafe { - std::env::set_var("CREDENTIALS_DIRECTORY", &cred_dir); - } - let specs = vec![KeySourceSpec::Credential("subdir".to_string())]; - let err = load_ring(&specs, &[]).unwrap_err(); - unsafe { - std::env::remove_var("CREDENTIALS_DIRECTORY"); - } - assert!( - err.contains("not a regular file"), - "credential directory should be rejected; got: {err}" - ); - } - - #[test] - fn load_ring_file_is_terminal() { - // file source with a nonexistent path should return an error - // immediately, NOT fall through to the next source. We verify this - // by putting a valid "environment" source after the bad file source: - // if file were skippable, load_ring would try environment and fail - // with "environment:" — instead it must fail with the file path. - let ghost_path = tdir("terminal-file").join("ghost.keys"); - let specs = vec![ - KeySourceSpec::File(ghost_path.clone()), - KeySourceSpec::Environment, - ]; - let err = load_ring(&specs, &[]).unwrap_err(); - assert!( - err.contains("ghost.keys"), - "file source should be terminal and error with the path; got: {err}" - ); - } - - #[test] - fn load_ring_file_rejects_nix_store() { - // file source under /nix/store must return immediately with an - // error, not fall through to a subsequent source. - let specs = vec![ - KeySourceSpec::File(std::path::PathBuf::from("/nix/store/abc/.env.keys")), - KeySourceSpec::Environment, - ]; - let err = load_ring(&specs, &[]).unwrap_err(); - assert!( - err.contains("Nix store"), - "file source under /nix/store should be terminal and reject; got: {err}" - ); - } - - #[test] - fn load_ring_environment_is_terminal() { - // environment source with no DOTENV_PRIVATE_KEY* vars should return - // an error immediately, not fall through. Since it's the last source, - // we verify the error is from from_env, not from the "no usable key - // source" fallback message. - // - // SAFETY: set_var/remove_var are unsafe on edition 2024 (not - // thread-safe). This test does not spawn threads. - let var_name = "DOTENV_PRIVATE_KEY_TESTTERMINAL"; - unsafe { - std::env::remove_var(var_name); - } - let specs = vec![ - KeySourceSpec::Credential("skipped".to_string()), - KeySourceSpec::Environment, - ]; - // Remove CREDENTIALS_DIRECTORY so credential is skippable. - unsafe { - std::env::remove_var("CREDENTIALS_DIRECTORY"); - } - let err = load_ring(&specs, &[]).unwrap_err(); - // The error must be from environment (terminal), not "no usable key - // source" (which would mean environment also fell through). - assert!( - !err.contains("no usable key source"), - "environment should be terminal, not fall through; got: {err}" - ); - } } diff --git a/src/lib.rs b/src/lib.rs index b5932f2..94b4b76 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,29 +1,55 @@ -//! postmaster library. +//! CLI dispatch and secret handling for Postmaster. //! -//! The bulk of the logic lives in the submodules so that unit tests can -//! exercise key loading, resolution, argument parsing, and serving logic -//! without going through main(). -//! -//! Security and fail-closed semantics are preserved exactly. +//! Submodules expose key loading, resolution, argument parsing, and serving +//! logic to tests without launching the binary entry point. -#![allow(missing_docs, missing_debug_implementations)] +// `multiple_crate_versions` is warn-level in Cargo.toml; allowed here for +// exactly one uncontrollable case: syn 2 + syn 3 coexist only because +// wasm-bindgen (target-gated to wasm32-unknown-unknown inside the ecies +// dependency, never compiled for postmaster's real targets) pins syn 2 +// while serde_derive uses syn 3. cargo-deny `[bans].multiple-versions` +// (warn, with syn skipped) keeps watch for the tree converging and for any +// NEW duplicates — remove this allow when syn 2 leaves the tree. +#![allow(clippy::multiple_crate_versions)] +mod aad; pub mod adapter; -pub mod bundle; -pub mod config; +pub mod cli; +pub mod exec_config; pub mod keys; pub mod launcher; +pub(crate) mod monitor; +pub mod ramdisk; +pub mod secret_files; pub mod server; +#[cfg(test)] +pub(crate) mod test_util; -pub use config::{Invocation, parse_args, parse_args_from}; +/// Public alias for the bundle adapter. +pub use adapter::bundle; +/// Public alias for CLI parsing and daemon configuration. +pub use cli as config; +pub use cli::{Invocation, parse_args, parse_args_from}; +pub use keys::provisioning::{cleanup, setup}; +/// Public alias for ordered key-source selection. +pub use keys::source as key_source; pub use server::{fetch, harden_process, run}; -/// Re-exported for binary use. The real main is here so tests can call into it. +/// Dispatch a parsed invocation from the binary or tests. pub fn main() -> std::process::ExitCode { - harden_process(); + // Harden only the arms that can touch secret material: --help/--version and --check + // must not print hardening noise (e.g. an mlockall failure) for invocations that + // never decrypt. Serve/Exec/Fetch/Setup/Cleanup stay hardened BEFORE any decryption + // and before execvp. let result = match parse_args() { - Ok(Invocation::Serve(args)) => run(&args), - Ok(Invocation::Fetch(path)) => fetch(&path), + Ok(Invocation::Serve(args)) => { + harden_process(); + run(&args) + } + Ok(Invocation::Fetch(path)) => { + harden_process(); + fetch(&path) + } Ok(Invocation::Exec { config, check: true, @@ -34,15 +60,24 @@ pub fn main() -> std::process::ExitCode { check: false, verify_keys, argv, - }) => launcher::exec(&config, &argv, verify_keys), + }) => { + harden_process(); + launcher::exec(&config, &argv, verify_keys) + } Ok(Invocation::Setup { config, recheck, unattended, force, keys_dir, - }) => launcher::setup(&config, recheck, unattended, force, keys_dir), - Ok(Invocation::Cleanup { config }) => launcher::cleanup(&config), + }) => { + harden_process(); + setup(&config, recheck, unattended, force, keys_dir) + } + Ok(Invocation::Cleanup { config }) => { + harden_process(); + cleanup(&config) + } #[allow(clippy::print_stdout, clippy::print_stderr)] Ok(Invocation::Help(sub)) => { let text = match sub.as_deref() { diff --git a/src/main.rs b/src/main.rs index 36379d6..4db66eb 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,8 +1,11 @@ //! Thin binary entry point. //! -//! Real logic (and all security properties) live in the library crate so -//! they can be unit-tested. See `lib.rs` and the submodule docs for the -//! full security posture, fail-closed design, and invariants. +//! The library crate owns CLI dispatch and secret handling so tests can call +//! those paths directly. See `lib.rs` and the submodule contracts. + +// See src/lib.rs for why this allow exists (wasm-bindgen's wasm32-gated +// syn 2 vs serde_derive's syn 3; uncontrollable, deny.toml keeps watch). +#![allow(clippy::multiple_crate_versions)] fn main() -> std::process::ExitCode { postmaster::main() diff --git a/src/monitor.rs b/src/monitor.rs new file mode 100644 index 0000000..d1d2c99 --- /dev/null +++ b/src/monitor.rs @@ -0,0 +1,503 @@ +//! Sibling launch monitor — a per-service fork-child that owns stop +//! semantics and plaintext cleanup on every service-death path. +//! +//! The launcher forks the monitor after validation, plaintext writes, and +//! zeroization of the key ring and resolved values, immediately before `execvp`. +//! The parent restores its +//! pre-guard signal mask and execs the service (MainPID unchanged), and +//! the fork-child becomes the monitor. Cleanup uses the +//! pinned secrets-dir fd (inherited across fork; `CLOEXEC` does not fire +//! because the monitor never execs) and the list of written entry names +//! — in env mode both are empty and cleanup is a no-op, but the monitor +//! still runs (uniform semantics: it forwards stops regardless). +//! The monitor scrubs projected env pairs, but retains the original process +//! environment. Environment-supplied private keys can remain there; filtering +//! the application's environment before exec does not erase the monitor's copy. +//! +//! Signal discipline: the four termination signals ({TERM, INT, HUP, +//! QUIT}) stay *blocked for the monitor's whole life* — the mask is +//! inherited from the launcher's `TerminationGuard` across fork and +//! re-asserted at monitor start — and are consumed synchronously via the +//! `sigpending`/`sigwait` family. No signal handlers exist anywhere in +//! the process. +//! SIGPIPE is additionally blocked so a stderr write to a closed pipe +//! cannot kill the monitor mid-supervision. +//! +//! Loop semantics (one tick = `POLL_INTERVAL`): +//! 1. A pending stop signal is dequeued → forward it to the service → +//! wait up to `GRACE` (250 ms constant — a single global security +//! policy, deliberately not configurable) for the service to die → +//! if still alive, `SIGKILL` → wait for death (unbounded: `SIGKILL` +//! cannot be blocked or ignored; only a D-state hang can delay it, and +//! abandoning cleanup is worse) → `cleanup_written` → exit. +//! 2. Otherwise, if the service is dead (liveness watch: pidfd + `poll` +//! on Linux, kqueue `EVFILT_PROC`/`NOTE_EXIT` on macOS, `kill(pid, 0)` +//! only as fallback) → `cleanup_written` → exit. This covers natural +//! exit, `kill -9`, and crashes. +//! 3. Otherwise, sleep one tick. Liveness/stop latency adds to cleanup +//! latency, never to the grace cap. +//! +//! Fork-child discipline (the soundness contract for `launcher.rs`'s +//! `fork`): the production fork parent is single-threaded at fork time, +//! so between fork and exit the monitor performs one bounded exception +//! and otherwise only the async-signal-safe syscall set. The exception: +//! the inherited `extra` env pairs (plaintext in env mode) are scrubbed +//! first — `wipe_pair` zeroizes in place, then drops (destructors and +//! `free()` in the child) — sound only because no other thread exists to +//! hold a malloc lock; under `cargo test` (multithreaded) test children +//! fork with an empty `extra`, so no child ever frees there. Otherwise: +//! no allocation, no stdio locks — only signal mask/wait ops, +//! `pidfd_open`/`poll`/`kevent`, `kill`/`pidfd_send_signal`, `unlinkat`, +//! `nanosleep`, raw `write(2)` for diagnostics, and `_exit`/`exit_group`. +//! All inputs (`names`, the dir fd) are allocated pre-fork and moved in. +//! Exit never runs destructors, atexit handlers, or stdio flushes +//! (inherited buffers must not flush twice). + +use std::os::fd::{AsFd, OwnedFd}; +use std::time::{Duration, Instant}; + +use rustix::io::Errno; +use rustix::process::{Pid, Signal, kill_process, test_kill_process}; +use zeroize::Zeroize; + +#[cfg(target_os = "linux")] +use rustix::event::{PollFd, PollFlags, poll}; +#[cfg(target_os = "linux")] +use rustix::process::{PidfdFlags, pidfd_open, pidfd_send_signal}; +#[cfg(target_os = "linux")] +use rustix::runtime_448b8ad740e2a26f::{self as runtime, KernelSigSet}; +#[cfg(target_os = "macos")] +use std::os::fd::{AsRawFd, FromRawFd}; + +use crate::secret_files::cleanup_written; + +/// Scrub one inherited env pair in place and return the wiped buffers +/// (threat model: monitor inherited heap). The fork-child monitor +/// inherits the launcher's `extra` env array — plaintext values in env +/// mode and in files-mode passthrough — and `free()` alone would leave +/// those bytes in the monitor's mapped pages for its whole life (the +/// monitor never allocates again, so they would never even be reused). +/// `into_vec` takes ownership of the existing `OsString` buffer with no +/// copy, and `zeroize` wipes it in place before the buffers are freed. +pub(crate) fn wipe_pair(k: std::ffi::OsString, v: std::ffi::OsString) -> (Vec, Vec) { + use std::os::unix::ffi::OsStringExt; + let mut kb = k.into_vec(); + let mut vb = v.into_vec(); + kb.zeroize(); + vb.zeroize(); + (kb, vb) +} + +/// The termination signals the monitor consumes synchronously and +/// forwards to the service. Also blocked across the launcher's +/// plaintext-write window (`TerminationGuard`) and inherited by the +/// monitor across fork. +pub(crate) const STOP_SIGNALS: [Signal; 4] = [Signal::TERM, Signal::INT, Signal::HUP, Signal::QUIT]; + +/// Grace between forwarding a stop signal and `SIGKILL` escalation: +/// 250 ms, a single global security policy (per-service erosion is +/// unacceptable; the per-unit knob is the service manager's own stop +/// timeout). Injectable in tests via `run_inner`. +pub(crate) const GRACE: Duration = Duration::from_millis(250); + +/// Liveness/poll tick. Short is fine: this latency adds to cleanup +/// latency, not to the grace cap. +pub(crate) const POLL_INTERVAL: Duration = Duration::from_millis(25); + +/// Zero timeout for non-blocking `poll(2)` liveness checks on the pidfd. +#[cfg(target_os = "linux")] +const ZERO_TIMESPEC: rustix::event::Timespec = rustix::event::Timespec { + tv_sec: 0, + tv_nsec: 0, +}; + +/// Monitor entry point with production timing. Never returns: the +/// monitor exits the process (via `_exit`/`exit_group`) once the service +/// is dead and the plaintext is cleaned. `dir_fd`/`names` are the pinned +/// secrets-dir fd and written entry names from the launcher; both are +/// absent in env mode (cleanup is then a no-op, but the monitor still +/// runs — uniform stop semantics). +pub(crate) fn run(service_pid: Pid, dir_fd: Option, names: Vec) -> ! { + run_inner(service_pid, dir_fd, names, GRACE, POLL_INTERVAL) +} + +/// The monitor loop, parameterized for deterministic tests. +fn run_inner( + service_pid: Pid, + dir_fd: Option, + names: Vec, + grace: Duration, + poll_interval: Duration, +) -> ! { + block_monitor_signals(); + let set = stop_sigset(); + let watch = Watch::new(service_pid); + loop { + if let Some(sig) = take_pending_stop(&set) { + // Stop semantics (diverges): forward, bounded grace, SIGKILL + // escalation, then clean and exit. + signal_service(&watch, service_pid, sig); + if !wait_for_death(&watch, service_pid, grace, poll_interval) { + monitor_log("postmaster monitor: grace expired; escalating to SIGKILL"); + signal_service(&watch, service_pid, Signal::KILL); + while !watch.dead(service_pid) { + std::thread::sleep(poll_interval); + } + } + cleanup_and_exit(dir_fd.as_ref(), &names); + } + if watch.dead(service_pid) { + // Service death from any cause: natural exit, kill -9, crash. + cleanup_and_exit(dir_fd.as_ref(), &names); + } + std::thread::sleep(poll_interval); + } +} + +/// Wait up to `grace` for the service to die. Returns true when death is +/// confirmed within the grace window. +fn wait_for_death(watch: &Watch, pid: Pid, grace: Duration, poll_interval: Duration) -> bool { + let deadline = Instant::now() + grace; + loop { + if watch.dead(pid) { + return true; + } + let now = Instant::now(); + if now >= deadline { + return false; + } + std::thread::sleep(poll_interval.min(deadline - now)); + } +} + +/// Unlink the written plaintext files (fd-relative, best-effort — an +/// already-vanished entry is ignored) and exit the monitor. Never +/// returns. +fn cleanup_and_exit(dir_fd: Option<&Fd>, names: &[String]) -> ! { + if let Some(fd) = dir_fd { + cleanup_written(fd, names); + } else if !names.is_empty() { + // Unreachable from the launcher (names are only tracked in fd + // modes); logged so a future caller regression is visible. + monitor_log("postmaster monitor: entry names without a directory fd; cannot clean"); + } + exit_process(0) +} + +/// Send `sig` to the service. Delivery errors (e.g. `ESRCH` because the +/// service died first) are ignored — the subsequent death wait settles +/// the outcome either way. +#[cfg(target_os = "linux")] +fn signal_service(watch: &Watch, pid: Pid, sig: Signal) { + // With a pidfd, signal through it: pidfd_send_signal(2) pins the + // process and cannot hit a recycled PID — the same PID-reuse + // rationale that makes pidfd the liveness choice. + if let Watch::Pidfd(fd) = watch { + let _ = pidfd_send_signal(fd, sig); + } else { + let _ = kill_process(pid, sig); + } +} + +/// Send `sig` to the service (see the Linux leg). Darwin has no pidfd, +/// so forwarding is plain kill(2); the bounded PID-reuse exposure on the +/// macOS stop path is documented in the threat model. +#[cfg(target_os = "macos")] +fn signal_service(_watch: &Watch, pid: Pid, sig: Signal) { + let _ = kill_process(pid, sig); +} + +/// Exit the monitor without running destructors, atexit handlers, or +/// stdio flushes — mandatory in a fork-child (inherited buffers and +/// handlers must not run twice; see module docs). +#[cfg(target_os = "linux")] +fn exit_process(code: i32) -> ! { + // exit_group(2) ≡ _exit(2): a safe rustix wrapper, no libc FFI. + runtime::exit_group(code) +} + +/// Exit the monitor (see the Linux leg). +#[cfg(target_os = "macos")] +fn exit_process(code: i32) -> ! { + // SAFETY: _exit(2) is async-signal-safe and callable from any + // context; it runs no handlers and flushes nothing — exactly the + // fork-child exit semantics required here. + unsafe { libc::_exit(code) } +} + +/// Best-effort diagnostic to stderr that stays inside the fork-child +/// discipline: a raw write(2) — no allocation, no stdio locks (the fork +/// parent may be multithreaded, e.g. under `cargo test`). SIGPIPE is +/// blocked for the monitor's life, so a closed pipe cannot kill us here. +fn monitor_log(msg: &str) { + // SAFETY: fd 2 is the process's stderr; if it has been closed the + // write simply fails with EBADF. The borrowed fd is not stored and + // does not outlive the call; nothing is closed. + let stderr = unsafe { std::os::fd::BorrowedFd::borrow_raw(2) }; + let _ = rustix::io::write(stderr, msg.as_bytes()); + let _ = rustix::io::write(stderr, b"\n"); +} + +/// The service liveness watch. Event sources (pidfd `POLLIN`, kqueue +/// `NOTE_EXIT`) fire at process exit — zombie- and PID-reuse-proof, +/// which is why they are the choice and `kill(pid, 0)` polling is only +/// the fallback (zombie-blind, PID-reuse-prone). +#[cfg(target_os = "linux")] +enum Watch { + /// pidfd(2) opened at monitor start; the fd pins the process. + Pidfd(OwnedFd), + /// kill(pid, 0) fallback for kernels without pidfd_open (< 5.3). + Poll, + /// The service was already dead when the monitor started. + Dead, +} + +#[cfg(target_os = "linux")] +impl Watch { + fn new(pid: Pid) -> Self { + match pidfd_open(pid, PidfdFlags::empty()) { + Ok(fd) => Self::Pidfd(fd), + // ESRCH is race-free "definitely gone" — clean up at once. + Err(Errno::SRCH) => Self::Dead, + // ENOSYS (old kernel), EMFILE, …: degrade to polling. + Err(_) => { + monitor_log( + "postmaster monitor: pidfd_open failed; falling back to kill(pid, 0) polling", + ); + Self::Poll + } + } + } + + fn dead(&self, pid: Pid) -> bool { + match self { + Self::Dead => true, + Self::Poll => matches!(test_kill_process(pid), Err(Errno::SRCH)), + Self::Pidfd(fd) => { + let mut fds = [PollFd::new(fd, PollFlags::IN)]; + match poll(&mut fds, Some(&ZERO_TIMESPEC)) { + // POLLIN: the process has terminated (fires at exit, + // not at reap — zombie-proof). POLLERR is treated as + // dead too: a pidfd that errors cannot supervise. + Ok(_) => fds[0].revents().intersects(PollFlags::IN | PollFlags::ERR), + // A failed poll means "unknown", not "dead": keep + // watching rather than abandon supervision. + Err(_) => false, + } + } + } + } +} + +/// The service liveness watch (see the Linux leg). +#[cfg(target_os = "macos")] +enum Watch { + /// kqueue with `EVFILT_PROC`/`NOTE_EXIT` registered for the service. + Kqueue(OwnedFd), + /// kill(pid, 0) fallback (kqueue creation failed — fd exhaustion). + Poll, + /// The service was already dead when the monitor started. + Dead, +} + +#[cfg(target_os = "macos")] +impl Watch { + fn new(pid: Pid) -> Self { + // ESRCH is race-free "definitely gone" — clean up at once. + if matches!(test_kill_process(pid), Err(Errno::SRCH)) { + return Self::Dead; + } + // SAFETY: kqueue(2) has no preconditions and returns a fresh + // queue fd on success. The kevent registration passes valid + // stack pointers and a well-formed changelist built from + // constants; a NULL timeout with an empty eventlist cannot block. + unsafe { + let kq = libc::kqueue(); + if kq == -1 { + monitor_log( + "postmaster monitor: kqueue failed; falling back to kill(pid, 0) polling", + ); + return Self::Poll; + } + let change = libc::kevent { + ident: pid.as_raw_pid() as usize, + filter: libc::EVFILT_PROC, + flags: libc::EV_ADD, + fflags: libc::NOTE_EXIT, + data: 0, + udata: std::ptr::null_mut(), + }; + if libc::kevent(kq, &change, 1, std::ptr::null_mut(), 0, std::ptr::null()) == -1 { + // With a changelist-only call, a knote error comes back + // as the kevent errno. ESRCH means the pid lookup failed + // because the service already exited (xnu drops exited + // procs from the pid table before they are reaped) — + // race-free "definitely gone", same as pidfd_open's ESRCH + // on Linux, so clean up at once rather than degrading to + // zombie-blind polling. + let dead = std::io::Error::last_os_error().raw_os_error() == Some(libc::ESRCH); + libc::close(kq); + if dead { + return Self::Dead; + } + monitor_log( + "postmaster monitor: kevent registration failed; falling back to kill(pid, 0) polling", + ); + return Self::Poll; + } + // SAFETY: kq is a fresh, valid fd owned by this process; + // wrapping it in OwnedFd closes it exactly once at drop. + Self::Kqueue(OwnedFd::from_raw_fd(kq)) + } + } + + fn dead(&self, pid: Pid) -> bool { + match self { + Self::Dead => true, + Self::Poll => matches!(test_kill_process(pid), Err(Errno::SRCH)), + Self::Kqueue(kq) => { + // SAFETY: `ev`/`ts` are valid stack locals that outlive + // the call; a zero timeout makes kevent(2) a non-blocking + // queue drain; the queue fd is valid (owned). + unsafe { + let mut ev: libc::kevent = std::mem::zeroed(); + let ts = libc::timespec { + tv_sec: 0, + tv_nsec: 0, + }; + if libc::kevent(kq.as_raw_fd(), std::ptr::null(), 0, &mut ev, 1, &ts) > 0 { + // The queue holds only the one NOTE_EXIT knote. + return true; + } + } + // Defense-in-depth net for any exit the knote misses + // (xnu attach subtleties): ESRCH is race-free "definitely + // gone". The registration-time case of this race returns + // Watch::Dead above instead. + matches!(test_kill_process(pid), Err(Errno::SRCH)) + } + } + } +} + +/// Block the stop signals plus `SIGPIPE` for the monitor's lifetime. +/// The four stop signals are normally already blocked by the launcher's +/// `TerminationGuard` and inherited across fork (blocking again is a +/// no-op); re-asserting keeps the monitor correct when the caller did +/// not pre-block (unit tests). `SIGPIPE` is monitor-local so the raw +/// stderr write in `monitor_log` cannot kill the monitor via a closed +/// pipe. A failure is logged and supervision continues: the inherited +/// mask is the common case, and failing to block cannot strand +/// plaintext by itself. +#[cfg(target_os = "linux")] +fn block_monitor_signals() { + let mut set = KernelSigSet::empty(); + for sig in STOP_SIGNALS { + set.insert(sig); + } + set.insert(Signal::PIPE); + // SAFETY: single-threaded fork-child; the set holds only standard + // signals — none reserved by a libc in the process (glibc reserves + // 32/33, untouched). Blocking these signals for life breaks no other + // code's assumptions: the monitor consumes the stop set synchronously + // and never installs handlers. + if unsafe { runtime::kernel_sigprocmask(runtime::How::BLOCK, Some(&set)) }.is_err() { + monitor_log("postmaster monitor: failed to block termination signals"); + } +} + +/// Block the stop signals plus `SIGPIPE` (see the Linux leg). +#[cfg(target_os = "macos")] +fn block_monitor_signals() { + // SAFETY: zeroed sigset_t is a valid empty set representation; all + // pointers are valid stack locals that outlive the calls; the pthread + // form is correct in single- and multi-threaded processes. + unsafe { + let mut set: libc::sigset_t = std::mem::zeroed(); + libc::sigemptyset(&mut set); + for sig in STOP_SIGNALS { + libc::sigaddset(&mut set, sig.as_raw()); + } + libc::sigaddset(&mut set, libc::SIGPIPE); + if libc::pthread_sigmask(libc::SIG_BLOCK, &set, std::ptr::null_mut()) != 0 { + monitor_log("postmaster monitor: failed to block termination signals"); + } + } +} + +/// The set of signals consumed synchronously by the loop. +#[cfg(target_os = "linux")] +fn stop_sigset() -> KernelSigSet { + let mut set = KernelSigSet::empty(); + for sig in STOP_SIGNALS { + set.insert(sig); + } + set +} + +/// The set of signals consumed synchronously by the loop. +#[cfg(target_os = "macos")] +fn stop_sigset() -> libc::sigset_t { + // SAFETY: zeroed sigset_t is a valid empty set representation; + // sigemptyset/sigaddset operate on a valid stack local. + unsafe { + let mut set: libc::sigset_t = std::mem::zeroed(); + libc::sigemptyset(&mut set); + for sig in STOP_SIGNALS { + libc::sigaddset(&mut set, sig.as_raw()); + } + set + } +} + +/// Dequeue a pending stop signal without blocking, if one is pending. +/// The signals are blocked for life, so they pend until consumed here — +/// synchronous consumption, no handlers anywhere. (Darwin has no +/// `sigtimedwait`, so both platforms use the portable +/// sigpending-then-sigwait form on the poll tick; the bounded stop +/// latency — one tick — is the latency the design explicitly budgets.) +#[cfg(target_os = "linux")] +fn take_pending_stop(set: &KernelSigSet) -> Option { + if !STOP_SIGNALS + .iter() + .any(|s| runtime::kernel_sigpending().contains(*s)) + { + return None; + } + // SAFETY: a signal from the set IS pending (checked above), so + // sigwait dequeues and returns immediately; the set holds only + // standard non-reserved signals; single-threaded here. + unsafe { runtime::kernel_sigwait(set) }.ok() +} + +/// Dequeue a pending stop signal without blocking (see the Linux leg). +#[cfg(target_os = "macos")] +fn take_pending_stop(set: &libc::sigset_t) -> Option { + // SAFETY: zeroed sigset_t is valid and sigpending fills it; sigwait + // is called only when a set member is pending, so it returns + // immediately; all pointers are valid stack locals. + unsafe { + let mut pending: libc::sigset_t = std::mem::zeroed(); + if libc::sigpending(&mut pending) != 0 { + return None; + } + if !STOP_SIGNALS + .iter() + .any(|s| libc::sigismember(&pending, s.as_raw()) == 1) + { + return None; + } + let mut got: libc::c_int = 0; + if libc::sigwait(set, &mut got) != 0 { + return None; + } + Signal::from_named_raw(got) + } +} + +#[cfg(not(any(target_os = "linux", target_os = "macos")))] +compile_error!("postmaster's sibling monitor supports Linux and macOS only"); + +// Keep monitor tests in a child module with access to the private implementation. +#[cfg(test)] +mod tests; diff --git a/src/monitor/tests.rs b/src/monitor/tests.rs new file mode 100644 index 0000000..c74c761 --- /dev/null +++ b/src/monitor/tests.rs @@ -0,0 +1,354 @@ +//! Sibling-monitor lifecycle, signal forwarding, cleanup, and heap-wiping tests. +#![allow(clippy::unwrap_used, clippy::panic)] + +use super::*; +use std::fs; +use std::io::Read; +use std::os::fd::AsRawFd; +use std::os::unix::process::ExitStatusExt; +use std::path::Path; +use std::process::Command; + +use rustix::process::{WaitOptions, waitpid}; + +use crate::launcher::TerminationGuard; +use crate::secret_files::open_secrets_dir; + +/// Keep fork callbacks separate from native-library initialization in other tests. +/// Return true when the current test completed in the isolated child process. +fn run_isolated() -> bool { + let thread = std::thread::current(); + let name = thread.name().unwrap(); + let args = ["--exact", name, "--nocapture"]; + if std::env::args_os() + .skip(1) + .eq(args.map(std::ffi::OsString::from)) + { + return false; + } + let output = Command::new(std::env::current_exe().unwrap()) + .args(args) + .output() + .unwrap(); + assert!( + output.status.success(), + "isolated {name}: {}\n{}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr), + ); + true +} + +fn tdir(tag: &str) -> crate::test_util::temp_dir::TestDir { + crate::test_util::temp_dir::TestDir::new(tag) +} + +/// Fork a monitor watching `service_pid`, mirroring the production +/// launcher: the calling thread blocks the stop signals first (the +/// child is born with them blocked — no ready-race between fork and +/// the monitor's own block), the fork-child runs the REAL monitor +/// loop with test-scaled timing, the parent restores its mask and +/// returns the monitor's pid. +fn fork_monitor( + service_pid: Pid, + dir: Option<&Path>, + names: Vec, + grace: Duration, + poll_interval: Duration, +) -> Pid { + let guard = TerminationGuard::block(); + let dir_fd = dir.map(|d| open_secrets_dir(d).unwrap()); + // SAFETY: fork(2) in the test process. The child executes only + // run_inner — documented async-signal-safe discipline: no + // allocation, no stdio locks, raw syscalls only — and then exits + // via _exit/exit_group, so the multithreaded test harness's + // malloc locks and output buffers are never touched in the child. + match unsafe { libc::fork() } { + -1 => panic!("fork: {}", std::io::Error::last_os_error()), + 0 => { + // Never returns (`-> !`), so the guard is never dropped + // and the mask stays blocked for the monitor's life + // (run_inner re-asserts it regardless). + run_inner(service_pid, dir_fd, names, grace, poll_interval); + } + child => { + guard.restore_mask(); + Pid::from_raw(child).unwrap() + } + } +} + +/// Reap the monitor, asserting it exits 0 within `timeout`. On +/// timeout the monitor is SIGKILLed and reaped so a regression fails +/// the test instead of hanging the suite. +fn wait_monitor_exit(pid: Pid, timeout: Duration) -> i32 { + let deadline = Instant::now() + timeout; + loop { + match waitpid(Some(pid), WaitOptions::NOHANG).unwrap() { + Some((_, status)) => { + if let Some(sig) = status.terminating_signal() { + panic!("monitor died by signal {sig}"); + } + return status.exit_status().unwrap_or(-1); + } + None => { + if Instant::now() >= deadline { + let _ = kill_process(pid, Signal::KILL); + let _ = waitpid(Some(pid), WaitOptions::empty()); + panic!("monitor did not exit within {timeout:?}"); + } + std::thread::sleep(Duration::from_millis(5)); + } + } + } +} + +fn write_dummies(dir: &Path) -> Vec { + fs::write(dir.join("A"), b"secret-a").unwrap(); + fs::write(dir.join("B"), b"secret-b").unwrap(); + vec!["A".to_string(), "B".to_string()] +} + +/// Reaps a forked/spawned pid on drop (SIGKILL first) so a failed +/// assertion can't leak a stray service process — important for the +/// TERM-ignoring service, which would otherwise outlive the test +/// binary indefinitely. +struct ReapOnDrop(Pid); + +impl Drop for ReapOnDrop { + fn drop(&mut self) { + let _ = kill_process(self.0, Signal::KILL); + let _ = waitpid(Some(self.0), WaitOptions::empty()); + } +} + +/// Fork a "service" that ignores SIGTERM until SIGKILLed: a +/// fork-child that sets TERM to SIG_IGN and pause()s forever. This +/// exercises the grace → SIGKILL escalation deterministically, unlike +/// a shell `trap` — macOS /bin/sh resets TERM for exec'd commands, +/// so the disposition doesn't survive into `sleep` there. The child +/// acknowledges readiness after installing SIG_IGN, before its pid returns. +fn fork_term_ignoring_service() -> Pid { + let (mut ready_read, ready_write) = std::io::pipe().unwrap(); + // SAFETY: fork(2) in the test process; the child executes only + // async-signal-safe calls (close, signal, write, pause, _exit) and + // never returns into the test harness — no allocation, stdio, or locks. + match unsafe { libc::fork() } { + -1 => panic!("fork: {}", std::io::Error::last_os_error()), + 0 => unsafe { + libc::close(ready_read.as_raw_fd()); + // SAFETY: plain single-threaded signal op on this + // process; SIG_IGN is the documented ignore-disposition + // constant. pause(2) suspends until a caught signal + // arrives; TERM is ignored, so only SIGKILL ends the loop. + if libc::signal(libc::SIGTERM, libc::SIG_IGN) == libc::SIG_ERR + || libc::write(ready_write.as_raw_fd(), b"R".as_ptr().cast(), 1) != 1 + { + libc::_exit(1); + } + libc::close(ready_write.as_raw_fd()); + loop { + libc::pause(); + } + }, + child => { + let pid = Pid::from_raw(child).unwrap(); + drop(ready_write); + if let Err(error) = ready_read.read_exact(&mut [0]) { + drop(ReapOnDrop(pid)); + panic!("service readiness: {error}"); + } + pid + } + } +} + +/// Service death NOT mediated by the monitor (kill -9 / crash +/// stand-in) must still trigger cleanup and monitor exit. +#[test] +fn natural_service_death_triggers_cleanup_and_monitor_exit() { + if run_isolated() { + return; + } + let dir = tdir("natural"); + let names = write_dummies(&dir); + let mut service = Command::new("sleep").arg("30").spawn().unwrap(); + let service_pid = Pid::from_child(&service); + let _reap = ReapOnDrop(service_pid); + let monitor = fork_monitor( + service_pid, + Some(&dir), + names, + Duration::from_millis(50), + Duration::from_millis(10), + ); + + assert!(dir.join("A").exists()); + kill_process(service_pid, Signal::KILL).unwrap(); + let status = service.wait().unwrap(); + assert_eq!(status.signal(), Some(libc::SIGKILL)); + + assert_eq!(wait_monitor_exit(monitor, Duration::from_secs(5)), 0); + assert!( + !dir.join("A").exists() && !dir.join("B").exists(), + "monitor must remove the plaintext files on service death" + ); + let _ = fs::remove_dir_all(&dir); +} + +/// A stop signal to the monitor is forwarded to the service; death +/// follows within the grace (no SIGKILL escalation needed), then +/// cleanup runs and the monitor exits 0. The monitor is born with +/// the signal blocked, so the TERM pends until its first tick — +/// no settle sleep is needed. +#[test] +fn stop_signal_is_forwarded_then_grace_then_cleanup() { + if run_isolated() { + return; + } + let dir = tdir("forward"); + let names = write_dummies(&dir); + let mut service = Command::new("sleep").arg("30").spawn().unwrap(); + let service_pid = Pid::from_child(&service); + let _reap = ReapOnDrop(service_pid); + let monitor = fork_monitor( + service_pid, + Some(&dir), + names, + Duration::from_millis(500), + Duration::from_millis(10), + ); + + kill_process(monitor, Signal::TERM).unwrap(); + + assert_eq!(wait_monitor_exit(monitor, Duration::from_secs(5)), 0); + let status = service.wait().unwrap(); + assert_eq!( + status.signal(), + Some(libc::SIGTERM), + "the service must die by the forwarded TERM, not by an escalated SIGKILL" + ); + assert!( + !dir.join("A").exists() && !dir.join("B").exists(), + "cleanup must run before the monitor exits" + ); + let _ = fs::remove_dir_all(&dir); +} + +/// A service that ignores SIGTERM is SIGKILLed only after the grace +/// elapses; cleanup still runs and the monitor exits 0. +#[test] +fn term_ignoring_service_is_sigkilled_after_grace() { + if run_isolated() { + return; + } + let dir = tdir("grace"); + let names = write_dummies(&dir); + let service_pid = fork_term_ignoring_service(); + let _reap = ReapOnDrop(service_pid); + let grace = Duration::from_millis(50); + let monitor = fork_monitor( + service_pid, + Some(&dir), + names, + grace, + Duration::from_millis(10), + ); + + let start = Instant::now(); + kill_process(monitor, Signal::TERM).unwrap(); + + assert_eq!(wait_monitor_exit(monitor, Duration::from_secs(5)), 0); + let Some((_, status)) = waitpid(Some(service_pid), WaitOptions::empty()).unwrap() else { + panic!("blocking waitpid returned no status"); + }; + assert_eq!( + status.terminating_signal(), + Some(libc::SIGKILL), + "a TERM-ignoring service must be SIGKILLed" + ); + assert!( + start.elapsed() >= grace, + "SIGKILL must not come before the grace elapses" + ); + assert!( + !dir.join("A").exists() && !dir.join("B").exists(), + "cleanup must run after the SIGKILL path" + ); + let _ = fs::remove_dir_all(&dir); +} + +/// The inherited-heap scrub (threat model): both buffers of an env +/// pair must come back fully wiped. +#[test] +fn wipe_pair_scrubs_both_buffers() { + let (k, v) = wipe_pair( + std::ffi::OsString::from("SECRET_NAME"), + std::ffi::OsString::from("s3cr3t-value"), + ); + assert!(k.iter().all(|b| *b == 0), "name buffer not wiped"); + assert!(v.iter().all(|b| *b == 0), "value buffer not wiped"); +} + +/// Uniform semantics (design decision 4): the monitor runs even in +/// env mode — no dir fd, an empty name list, cleanup a no-op — and +/// still exits when the service dies. +#[test] +fn env_mode_monitor_with_no_files_exits_on_service_death() { + if run_isolated() { + return; + } + let mut service = Command::new("sleep").arg("30").spawn().unwrap(); + let service_pid = Pid::from_child(&service); + let _reap = ReapOnDrop(service_pid); + let monitor = fork_monitor( + service_pid, + None, + Vec::new(), + Duration::from_millis(50), + Duration::from_millis(10), + ); + + kill_process(service_pid, Signal::TERM).unwrap(); + let status = service.wait().unwrap(); + assert_eq!(status.signal(), Some(libc::SIGTERM)); + + assert_eq!(wait_monitor_exit(monitor, Duration::from_secs(5)), 0); +} + +/// A service that is ALREADY dead when the monitor starts (death +/// observed on the first tick) must still trigger cleanup and an +/// immediate monitor exit — the monitor must never hang waiting on a +/// process that died before it began watching. +#[test] +fn pre_dead_service_triggers_immediate_cleanup_and_exit() { + if run_isolated() { + return; + } + let dir = tdir("predead"); + let names = write_dummies(&dir); + let mut service = Command::new("sleep").arg("30").spawn().unwrap(); + let service_pid = Pid::from_child(&service); + // Kill AND reap before the monitor starts: a zombie still answers + // kill(pid, 0), so the monitor would correctly see "alive". After + // the reap the pid is gone (ESRCH); reuse inside the test window + // is negligible. + kill_process(service_pid, Signal::KILL).unwrap(); + let status = service.wait().unwrap(); + assert_eq!(status.signal(), Some(libc::SIGKILL)); + + let monitor = fork_monitor( + service_pid, + Some(&dir), + names, + Duration::from_millis(50), + Duration::from_millis(10), + ); + + assert_eq!(wait_monitor_exit(monitor, Duration::from_secs(5)), 0); + assert!( + !dir.join("A").exists() && !dir.join("B").exists(), + "cleanup must run even when the service died before the monitor started" + ); + let _ = fs::remove_dir_all(&dir); +} diff --git a/src/ramdisk.rs b/src/ramdisk.rs new file mode 100644 index 0000000..ed550c5 --- /dev/null +++ b/src/ramdisk.rs @@ -0,0 +1,381 @@ +//! macOS ramdisk verification — ensures plaintext secret files land only +//! beneath a verified RAM-backed HFS mount: the mount proves RAM-backed +//! via hdiutil, and the pinned `secrets_dir` must use that device and be +//! owned by the service user. The final component cannot be a symlink. +//! +//! The launcher uses this check when `verify_ramdisk` is configured on macOS. +//! Linux integrations provide and secure their own RAM-backed storage. + +use std::fs; +use std::os::fd::OwnedFd; +use std::os::unix::fs::{FileTypeExt, MetadataExt}; +use std::path::Path; + +/// Pure parser for /sbin/mount output: is `mp` mounted as HFS? +fn mount_lists_hfs(mount_out: &str, mp: &Path) -> bool { + // Strip trailing slashes so a mount point like "/foo/" matches + // "/foo" in mount output (which never includes trailing slashes). + let mp_str = mp.to_string_lossy(); + let mp_trimmed = mp_str.trim_end_matches('/'); + let needle = format!(" on {mp_trimmed} (hfs"); + mount_out.lines().any(|l| l.contains(&needle)) +} + +/// Extract the device path for a mount point from `mount` output. +/// Format: `/dev/disk8 on /path (hfs, ...)` → `/dev/disk8`. +fn mount_device_for(mount_out: &str, mp: &Path) -> Option { + let mp_str = mp.to_string_lossy(); + let mp_trimmed = mp_str.trim_end_matches('/'); + let needle = format!(" on {mp_trimmed} (hfs"); + for line in mount_out.lines() { + if let Some(idx) = line.find(&needle) { + // The device is everything before " on " + let device = &line[..idx].trim(); + if !device.is_empty() { + return Some(device.to_string()); + } + } + } + None +} + +/// Verify that a device is backed by RAM (not a file-backed disk image). +/// Parses `hdiutil info` text output for the device's `image-path` +/// field and checks it starts with `ram://`. +fn device_is_ram_backed(device: &str, hdiutil_out: &str) -> bool { + // hdiutil info output structure (per image entry): + // image-path : ram://1024 + // image-type : read/write + // ... + // /dev/disk8 /Volumes/Postmaster + // + // Device rows can include partition types and mount paths. Match the + // first token, then find image-path within the same image entry. + + let lines: Vec<&str> = hdiutil_out.lines().collect(); + let device_line = device.trim(); + for (idx, line) in lines.iter().enumerate() { + if line.split_whitespace().next() == Some(device_line) { + // Scan backwards from the device line to find image-path + for prev in lines[..idx].iter().rev() { + let trimmed = prev.trim(); + if let Some((name, value)) = trimmed.split_once(':') + && name.trim() == "image-path" + { + return value.trim().starts_with("ram://"); + } + // Partition rows share image properties; only the image + // separator ends the search. + if trimmed.starts_with("====") { + break; + } + } + return false; + } + } + false +} + +/// True when `dir` names a path lexically beneath `mount_point` +/// (component-wise, with no `..` escape). This lexical filter must be paired +/// with a backing-device check on the opened directory. +fn path_beneath(dir: &Path, mount_point: &Path) -> bool { + match dir.strip_prefix(mount_point) { + Ok(rest) => !rest + .components() + .any(|c| matches!(c, std::path::Component::ParentDir)), + Err(_) => false, + } +} + +/// Verify a macOS RAM-backed mount and a contained directory owned by this user. +/// +/// This verification-only API does not retain the directory handle. The +/// launcher uses `open_verified_ramdisk_dir` to keep the verified inode pinned. +pub fn verify_ramdisk(mount_point: &Path, secrets_dir: &Path) -> Result<(), String> { + open_verified_ramdisk_dir(mount_point, secrets_dir).map(drop) +} + +/// Verify the RAM backing and return the pinned directory for plaintext I/O. +pub(crate) fn open_verified_ramdisk_dir( + mount_point: &Path, + secrets_dir: &Path, +) -> Result { + // Trust boundary: a compromised /sbin/mount or hdiutil could report persistent disk + // as the RAM-backed postmaster ramdisk and let plaintext land on persistent + // storage. Verify both helpers before invoking. + crate::keys::verify_external_binary(Path::new("/sbin/mount"))?; + crate::keys::verify_external_binary(Path::new("/usr/bin/hdiutil"))?; + let out = std::process::Command::new("/sbin/mount") + .output() + .map_err(|e| format!("/sbin/mount: {e}"))?; + let text = String::from_utf8_lossy(&out.stdout); + if !mount_lists_hfs(&text, mount_point) { + return Err(format!( + "{}: not the postmaster ramdisk; refusing to write plaintext to persistent disk", + mount_point.display() + )); + } + // Verify the mount is RAM-backed, not a file-backed HFS image. + // Extract the device from mount output, then check hdiutil info + // for that device's image-path starting with ram://. + let device = mount_device_for(&text, mount_point).ok_or_else(|| { + format!( + "{}: could not determine backing device from mount output", + mount_point.display() + ) + })?; + let hdiutil_out = std::process::Command::new("/usr/bin/hdiutil") + .arg("info") + .output() + .map_err(|e| format!("hdiutil info: {e}"))?; + let hdiutil_text = String::from_utf8_lossy(&hdiutil_out.stdout); + if !device_is_ram_backed(&device, &hdiutil_text) { + return Err(format!( + "{}: mount device {device} is not RAM-backed (image-path does not start with ram://); refusing to write plaintext to a file-backed disk image", + mount_point.display() + )); + } + let device_md = fs::metadata(&device).map_err(|e| format!("{device}: {e}"))?; + if !device_md.file_type().is_block_device() { + return Err(format!( + "{device}: ramdisk backing device is not a block device" + )); + } + open_verified_dir(mount_point, secrets_dir, device_md.rdev()) +} + +/// Pin a contained, service-owned directory on the expected backing device. +fn open_verified_dir( + mount_point: &Path, + secrets_dir: &Path, + device: u64, +) -> Result { + if !path_beneath(secrets_dir, mount_point) { + return Err(format!( + "{}: secrets_dir is not beneath the verified ramdisk mount {}; refusing to write plaintext outside the ramdisk", + secrets_dir.display(), + mount_point.display() + )); + } + let fd = crate::secret_files::open_secrets_dir(secrets_dir).map_err(|e| { + format!( + "{}: {e} (refusing a symlinked or non-directory secrets_dir)", + secrets_dir.display() + ) + })?; + let dir = fs::File::from(fd); + let md = dir.metadata().map_err(|e| { + format!( + "{}: {e} (is postmaster-ramdisk healthy?)", + secrets_dir.display() + ) + })?; + if !md.is_dir() || md.uid() != rustix::process::geteuid().as_raw() { + return Err(format!( + "{}: missing or not owned by this service user (is postmaster-ramdisk healthy?)", + secrets_dir.display() + )); + } + // O_NOFOLLOW covers only the final component; an ancestor can redirect + // the open. Check the pinned inode, then retain it for every plaintext I/O. + if md.dev() != device { + return Err(format!( + "{}: secrets_dir is not on the verified ramdisk device; refusing to write plaintext outside the ramdisk", + secrets_dir.display() + )); + } + Ok(dir.into()) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic)] +mod tests { + use super::*; + use std::path::Path; + + #[test] + fn mount_guard_parses_mount_output() { + let out = "/dev/disk3 on / (apfs, local)\n/dev/disk7 on /private/var/run/postmaster (hfs, local, nodev, nosuid, noexec)\n"; + assert!(mount_lists_hfs( + out, + Path::new("/private/var/run/postmaster") + )); + assert!(!mount_lists_hfs(out, Path::new("/private/var/run/other"))); + assert!(!mount_lists_hfs("/dev/disk3 on / (apfs)\n", Path::new("/"))); + } + + #[test] + fn mount_device_for_extracts_device() { + let out = "/dev/disk3 on / (apfs, local)\n/dev/disk7 on /private/var/run/postmaster (hfs, local, nodev, nosuid, noexec)\n"; + assert_eq!( + mount_device_for(out, Path::new("/private/var/run/postmaster")), + Some("/dev/disk7".to_string()) + ); + assert_eq!(mount_device_for(out, Path::new("/nonexistent")), None); + } + + #[test] + fn device_is_ram_backed_detects_ram_prefix() { + let hdiutil = "\ +framework : 683.100.3 +driver : 683.100.3 +================================================ +image-path : ram://1024 +shadow-path : +icon-path : /System/Library/PrivateFrameworks/DiskImages.framework/Resources/CDiskImage.icns +image-type : read/write +system-image : false +blockcount : 1024 +blocksize : 512 +writeable : TRUE +autodiskmount : false +removable : TRUE +-- +framework name : DiskImages +/dev/disk8 +"; + assert!(device_is_ram_backed("/dev/disk8", hdiutil)); + + let hdiutil_file = "\ +================================================ +image-path : /Users/user/image.dmg +shadow-path : +image-type : read/write +/dev/disk9 +"; + assert!(!device_is_ram_backed("/dev/disk9", hdiutil_file)); + + // Device not in hdiutil output at all + assert!(!device_is_ram_backed("/dev/disk99", hdiutil)); + } + + #[test] + fn device_is_ram_backed_accepts_mounted_device_columns() { + let output = "================================================\n\ + image-path : ram://32768\n\ + /dev/disk5\t\t/Volumes/Postmaster Test\n"; + assert!(device_is_ram_backed("/dev/disk5", output)); + assert!(!device_is_ram_backed("/dev/disk", output)); + assert!(!device_is_ram_backed("/dev/disk50", output)); + } + + #[test] + fn device_is_ram_backed_keeps_partition_rows_in_their_image() { + let output = "================================================\n\ + image-path : ram://32768\n\ + /dev/disk8\tGUID_partition_scheme\n\ + /dev/disk8s1\tApple_HFS\t/Volumes/RAM\n\ + =================================================\n\ + image-path : /tmp/file-backed.dmg\n\ + /dev/disk9\tGUID_partition_scheme\n\ + /dev/disk9s1\tApple_HFS\t/Volumes/File Image\n\ + =================================================\n\ + image-path-other: ram://32768\n\ + /dev/disk10\t\t/Volumes/Unknown\n"; + for (device, expected) in [ + ("/dev/disk8", true), + ("/dev/disk8s1", true), + ("/dev/disk9", false), + ("/dev/disk9s1", false), + ("/dev/disk10", false), + ] { + assert_eq!(device_is_ram_backed(device, output), expected, "{device}"); + } + } + + #[test] + fn path_beneath_enforces_containment() { + // The guard must relate secrets_dir to the verified mount, not check each + // independently. + let mp = Path::new("/private/var/run/postmaster"); + assert!(path_beneath( + Path::new("/private/var/run/postmaster/myapp"), + mp + )); + assert!(path_beneath(mp, mp), "the mount root itself is contained"); + assert!(!path_beneath(Path::new("/private/var/run/other"), mp)); + // Component-wise: a sibling whose name merely shares a prefix is + // NOT contained. + assert!(!path_beneath( + Path::new("/private/var/run/postmaster-evil"), + mp + )); + // `..` escape after a lexical prefix is rejected. + assert!(!path_beneath( + Path::new("/private/var/run/postmaster/../other"), + mp + )); + } + + fn test_dir(tag: &str) -> crate::test_util::temp_dir::TestDir { + crate::test_util::temp_dir::TestDir::new(tag) + } + + #[test] + fn verified_dir_rejects_an_intermediate_link_to_another_device() { + let root = test_dir("ancestor-link"); + let mount = root.join("mount"); + let outside = root.join("outside"); + fs::create_dir(&mount).unwrap(); + fs::create_dir_all(outside.join("service")).unwrap(); + std::os::unix::fs::symlink(&outside, mount.join("link")).unwrap(); + let candidate = mount.join("link/service"); + assert!(path_beneath(&candidate, &mount)); + assert!(fs::symlink_metadata(&candidate).unwrap().is_dir()); + // Inject a different device ID; /dev can share the build filesystem. + let expected_device = fs::metadata(&candidate).unwrap().dev() ^ 1; + + let err = open_verified_dir(&mount, &candidate, expected_device).unwrap_err(); + + assert!(err.contains("not on the verified ramdisk device"), "{err}"); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn verified_dir_allows_internal_links_but_rejects_a_final_symlink() { + let root = test_dir("internal-link"); + let service = root.join("nested/service"); + fs::create_dir_all(&service).unwrap(); + std::os::unix::fs::symlink(root.join("nested"), root.join("link")).unwrap(); + let device = fs::metadata(&root).unwrap().dev(); + let fd = open_verified_dir(&root, &root.join("link/service"), device).unwrap(); + assert_eq!( + fs::File::from(fd).metadata().unwrap().ino(), + fs::metadata(&service).unwrap().ino() + ); + std::os::unix::fs::symlink(&service, root.join("final")).unwrap(); + let err = open_verified_dir(&root, &root.join("final"), device).unwrap_err(); + assert!(err.contains("symlinked"), "{err}"); + fs::remove_dir_all(root).unwrap(); + } + + #[test] + fn verified_handle_pins_prune_write_and_cleanup_across_path_replacement() { + use crate::secret_files::{cleanup_written, prune_stale_at, write_secret_file}; + + let root = test_dir("path-replacement"); + let service = root.join("service"); + let original = root.join("original"); + let outside = root.join("outside"); + fs::create_dir(&service).unwrap(); + fs::create_dir(&outside).unwrap(); + let device = fs::metadata(&root).unwrap().dev(); + let fd = open_verified_dir(&root, &service, device).unwrap(); + write_secret_file(&fd, &service, "OLD", b"stale").unwrap(); + fs::write(outside.join("OLD"), b"foreign-old").unwrap(); + fs::write(outside.join("SECRET"), b"foreign-secret").unwrap(); + fs::rename(&service, &original).unwrap(); + std::os::unix::fs::symlink(&outside, &service).unwrap(); + + prune_stale_at(&fd, &service, &[]).unwrap(); + assert!(!original.join("OLD").exists()); + assert_eq!(fs::read(outside.join("OLD")).unwrap(), b"foreign-old"); + write_secret_file(&fd, &service, "SECRET", b"test-secret").unwrap(); + assert_eq!(fs::read(original.join("SECRET")).unwrap(), b"test-secret"); + cleanup_written(&fd, &["SECRET".into()]); + assert!(!original.join("SECRET").exists()); + assert_eq!(fs::read(outside.join("SECRET")).unwrap(), b"foreign-secret"); + fs::remove_dir_all(root).unwrap(); + } +} diff --git a/src/secret_files.rs b/src/secret_files.rs new file mode 100644 index 0000000..efe9219 --- /dev/null +++ b/src/secret_files.rs @@ -0,0 +1,678 @@ +//! Secret file operations — writing, cleanup, and pruning of plaintext +//! secret files on RAM-backed filesystems. +//! +//! The secrets directory is pinned by an open fd (`O_DIRECTORY|O_NOFOLLOW`), +//! and permissions are checked on opened inodes. Subsequent +//! output creation, entry checks, and cleanup are relative to that pinned inode. +//! Exported-path validation separately checks lexical and resolved ancestry. + +use std::ffi::OsString; +use std::fs; +use std::io::Write; +use std::os::fd::{AsFd, OwnedFd}; +use std::os::unix::ffi::OsStringExt; +use std::path::{Path, PathBuf}; + +use zeroize::Zeroizing; + +#[cfg(target_os = "macos")] +mod acl; + +/// Remove extended grants before writing private file contents. +pub(crate) fn clear_file_acl(fd: impl AsFd) -> Result<(), String> { + #[cfg(target_os = "macos")] + acl::clear(fd)?; + #[cfg(not(target_os = "macos"))] + let _ = fd; + Ok(()) +} + +/// Check private-file ACL grants on the opened inode without changing it. +pub(crate) fn validate_private_file_acl(fd: impl AsFd) -> Result<(), String> { + #[cfg(target_os = "macos")] + acl::validate_private_file(fd)?; + #[cfg(not(target_os = "macos"))] + let _ = fd; + Ok(()) +} + +/// Resolved values keyed by name, each zeroized on drop. +pub type Resolved = Vec<(String, Zeroizing>)>; + +/// Marker file postmaster creates in any secrets_dir it writes to. +/// `prune_stale` and `cleanup` refuse to +/// bulk-delete in a non-empty directory that lacks it — foreign files +/// could be present. A permission-mode check cannot make that +/// distinction: the Linux files-mode secrets dir is a namespace-private +/// tmpfs systemd mounts 1777, which is dedicated yet world-accessible. +pub const MANAGED_SENTINEL: &str = ".postmaster-managed"; + +/// Resolved values → env pairs. Env values cannot hold NUL; fail closed +/// rather than truncate. +pub fn env_pairs(resolved: &Resolved) -> Result, String> { + let mut out = Vec::with_capacity(resolved.len()); + for (k, v) in resolved { + if v.contains(&0) { + return Err(format!( + "{k}: value contains a NUL byte; cannot be an environment variable (use files mode)" + )); + } + out.push((OsString::from(k.clone()), OsString::from_vec(v.to_vec()))); + } + Ok(out) +} + +/// Open and pin a secrets directory by fd: `O_RDONLY|O_DIRECTORY| +/// O_NOFOLLOW|O_CLOEXEC` rejects a final-component symlink or non-directory and +/// pins the inode, so subsequent `*at` operations are relative to it +/// rather than to a re-resolved path. +pub(crate) fn open_secrets_dir(dir: &Path) -> rustix::io::Result { + rustix::fs::open( + dir, + rustix::fs::OFlags::RDONLY + | rustix::fs::OFlags::DIRECTORY + | rustix::fs::OFlags::NOFOLLOW + | rustix::fs::OFlags::CLOEXEC, + rustix::fs::Mode::empty(), + ) +} + +/// Verify every lexical and resolved ancestor before exporting a pathname. +/// Root and the effective user are trusted; sticky shared parents protect their entries. +pub(crate) fn validate_directory_path(dir: &Path) -> Result { + use std::os::unix::fs::MetadataExt as _; + let absolute = if dir.is_absolute() { + dir.to_path_buf() + } else { + std::env::current_dir() + .map_err(|e| format!("current directory: {e}"))? + .join(dir) + }; + let euid = rustix::process::geteuid().as_raw(); + let check = |path: &Path, symlink: bool| -> Result<(), String> { + let md = fs::symlink_metadata(path).map_err(|e| format!("{}: {e}", path.display()))?; + if md.uid() != 0 && md.uid() != euid { + return Err(format!( + "{}: directory path is owned by an untrusted user", + path.display() + )); + } + if symlink && md.file_type().is_symlink() { + return Ok(()); + } + if !md.is_dir() || md.mode() & 0o022 != 0 && md.mode() & 0o1000 == 0 { + return Err(format!( + "{}: directory path permits untrusted replacement", + path.display() + )); + } + #[cfg(target_os = "macos")] + { + let fd = open_secrets_dir(path).map_err(|e| format!("{}: {e}", path.display()))?; + acl::validate(&fd).map_err(|e| format!("{}: {e}", path.display()))?; + } + Ok(()) + }; + let mut lexical = PathBuf::new(); + for component in absolute.components() { + lexical.push(component); + check(&lexical, true)?; + // Check symlink targets too: trusting the link alone does not protect its target. + let resolved = + fs::canonicalize(&lexical).map_err(|e| format!("{}: {e}", lexical.display()))?; + let mut prefix = PathBuf::new(); + for component in resolved.components() { + prefix.push(component); + check(&prefix, false)?; + } + } + fs::canonicalize(&absolute).map_err(|e| format!("{}: {e}", absolute.display())) +} + +/// Check that an exported directory still names the inode used for writes. +pub(crate) fn validate_projection(dir_fd: impl AsFd, dir: &Path) -> Result { + use std::os::unix::fs::MetadataExt as _; + let canonical = validate_directory_path(dir)?; + let pinned = rustix::fs::fstat(dir_fd).map_err(|e| format!("{}: stat: {e}", dir.display()))?; + let named = fs::metadata(&canonical).map_err(|e| format!("{}: {e}", dir.display()))?; + #[cfg(target_os = "macos")] + let device = pinned.st_dev as u64; + #[cfg(target_os = "linux")] + let device = pinned.st_dev; + if device != named.dev() || pinned.st_ino != named.ino() { + return Err(format!( + "{}: directory changed during validation", + dir.display() + )); + } + Ok(canonical) +} + +/// Enumerate entry names beneath an already-pinned directory fd, +/// excluding `.` and `..`. `Dir::read_from` re-opens `.` beneath the +/// fd, so enumeration is relative to the pinned inode and the caller's +/// fd offset is untouched. A directory removed after it was pinned +/// reads as empty. +pub(crate) fn read_dir_names(dir_fd: impl AsFd) -> rustix::io::Result> { + let reader = match rustix::fs::Dir::read_from(dir_fd) { + Ok(r) => r, + // Raced away between the open and here: nothing inside. + Err(rustix::io::Errno::NOENT) => return Ok(Vec::new()), + Err(e) => return Err(e), + }; + let mut names = Vec::new(); + for entry in reader { + let entry = entry?; + let name = entry.file_name().to_bytes(); + if name == b"." || name == b".." { + continue; + } + names.push(OsString::from_vec(name.to_vec())); + } + Ok(names) +} + +/// Reject foreign, linked or special existing files before publication. +pub(crate) fn check_file(dir_fd: impl AsFd, name: &std::ffi::OsStr) -> Result<(), String> { + use rustix::fs::{AtFlags, FileType, statat}; + match statat(dir_fd, name, AtFlags::SYMLINK_NOFOLLOW) { + Ok(st) + if FileType::from_raw_mode(st.st_mode) == FileType::RegularFile + && st.st_uid == rustix::process::geteuid().as_raw() + && st.st_nlink == 1 => + { + Ok(()) + } + Ok(_) => Err("refusing foreign, linked or non-regular file".into()), + Err(rustix::io::Errno::NOENT) => Ok(()), + Err(e) => Err(format!("stat: {e}")), + } +} + +/// Publish a fresh owner-only inode beneath a pinned directory. +/// Existing read handles retain the old contents. Failed writes remove only the new inode. +pub(crate) fn replace_file( + dir_fd: impl AsFd, + name: &std::ffi::OsStr, + value: &[u8], +) -> Result<(), String> { + use rustix::fs::{AtFlags, Mode, OFlags, openat, renameat, unlinkat}; + let dir_fd = dir_fd.as_fd(); + check_file(dir_fd, name)?; + #[cfg(target_os = "macos")] + acl::validate(dir_fd)?; + let mut random = [0; 16]; + getrandom::fill(&mut random).map_err(|e| format!("random temporary name: {e}"))?; + let temporary = format!(".postmaster-{}", hex::encode(random)); + let fd = openat( + dir_fd, + temporary.as_str(), + OFlags::WRONLY | OFlags::CREATE | OFlags::EXCL | OFlags::NOFOLLOW | OFlags::CLOEXEC, + Mode::RUSR | Mode::WUSR, + ) + .map_err(|e| format!("create temporary file: {e}"))?; + let result = (|| { + rustix::fs::fchmod(&fd, Mode::RUSR | Mode::WUSR).map_err(|e| format!("fchmod: {e}"))?; + clear_file_acl(&fd)?; + let mut file = fs::File::from(fd); + file.write_all(value) + .and_then(|()| file.flush()) + .map_err(|e| format!("write: {e}"))?; + check_file(dir_fd, name)?; + renameat(dir_fd, temporary.as_str(), dir_fd, name).map_err(|e| format!("publish: {e}")) + })(); + if result.is_err() { + let _ = unlinkat(dir_fd, temporary.as_str(), AtFlags::empty()); + } + result +} + +/// Write a fresh 0600 file beneath the pinned directory and return its consumer path. +/// Refuse foreign, linked and special existing entries; refresh regular owner-held files atomically. +pub fn write_secret_file( + dir_fd: impl AsFd, + dir: &Path, + key: &str, + value: &[u8], +) -> Result { + if !crate::keys::is_ident(key) { + return Err("secret filename must be an identifier".into()); + } + let dir_fd = dir_fd.as_fd(); + let path = dir.join(key); + let sentinel = std::ffi::OsStr::new(MANAGED_SENTINEL); + check_file(dir_fd, sentinel).map_err(|e| format!("{}: sentinel: {e}", path.display()))?; + let sentinel_fd = rustix::fs::openat( + dir_fd, + sentinel, + rustix::fs::OFlags::WRONLY + | rustix::fs::OFlags::CREATE + | rustix::fs::OFlags::EXCL + | rustix::fs::OFlags::NOFOLLOW + | rustix::fs::OFlags::CLOEXEC, + rustix::fs::Mode::RUSR | rustix::fs::Mode::WUSR, + ); + match sentinel_fd { + Ok(fd) => { + clear_file_acl(&fd)?; + } + Err(rustix::io::Errno::EXIST) => { + check_file(dir_fd, sentinel) + .map_err(|e| format!("{}: sentinel: {e}", path.display()))?; + } + Err(e) => return Err(format!("{}: sentinel: {e}", path.display())), + } + replace_file(dir_fd, std::ffi::OsStr::new(key), value) + .map_err(|e| format!("{}: {e}", path.display()))?; + Ok(path) +} + +/// Unlink the named entries beneath the pinned secrets-dir fd +/// (best-effort) after a mid-loop failure so stale plaintext files do +/// not persist on the ramdisk/tmpfs. Unlinking by NAME relative to the +/// pinned fd (not by path) keeps the deletes on the inode the writes +/// went to even if the directory path has been swapped since. The +/// caller must only push names of successfully-written secret files +/// here; an already-vanished entry is ignored. +pub fn cleanup_written(dir_fd: impl AsFd, names: &[String]) { + let dir_fd = dir_fd.as_fd(); + for name in names { + let _ = rustix::fs::unlinkat(dir_fd, name, rustix::fs::AtFlags::empty()); + } +} + +/// Prune stale secret files from `dir` that are not in `keep_keys`. This +/// removes plaintext files left behind by a previous launch whose config +/// has since changed (a key removed from credential_keys or a resolved key +/// set that no longer includes a prior entry). Best-effort: logs but does +/// not fail if a file cannot be removed, since the primary invariant — +/// plaintext is transient — is best served by cleaning what we can rather +/// than aborting the launch over an unrelated stale file. +pub fn prune_stale(dir: &Path, keep_keys: &[String]) -> Result<(), String> { + // Pin the directory by fd: O_DIRECTORY|O_NOFOLLOW rejects a symlinked or + // non-directory secrets dir at open, and the sentinel check, the per-entry stat, + // and every unlink below are all relative to the pinned inode — no path is ever + // re-resolved. + let dir_fd = match open_secrets_dir(dir) { + Ok(fd) => fd, + // If the directory does not exist yet, there is nothing to prune. + Err(rustix::io::Errno::NOENT) => return Ok(()), + Err(e @ (rustix::io::Errno::LOOP | rustix::io::Errno::NOTDIR)) => { + return Err(format!( + "{}: prune: refusing a symlinked or non-directory secrets dir ({e})", + dir.display() + )); + } + Err(e) => return Err(format!("{}: prune: {e}", dir.display())), + }; + prune_stale_at(&dir_fd, dir, keep_keys) +} + +/// Prune through the same pinned directory used for verification and writes. +pub(crate) fn prune_stale_at( + dir_fd: impl AsFd, + dir: &Path, + keep_keys: &[String], +) -> Result<(), String> { + let dir_fd = dir_fd.as_fd(); + let keep: std::collections::HashSet<&str> = keep_keys.iter().map(String::as_str).collect(); + let names = read_dir_names(dir_fd).map_err(|e| format!("{}: prune: {e}", dir.display()))?; + // An empty directory is trivially safe (first launch). + if names.is_empty() { + return Ok(()); + } + // Managed-dir guard: non-empty and no sentinel means postmaster never wrote here — + // bulk deletes could hit foreign files. Refuse. + match rustix::fs::statat( + dir_fd, + MANAGED_SENTINEL, + rustix::fs::AtFlags::SYMLINK_NOFOLLOW, + ) { + Ok(stat) if rustix::fs::FileType::from_raw_mode(stat.st_mode).is_file() => {} + _ => { + return Err(format!( + "{}: prune: no {MANAGED_SENTINEL} sentinel; refusing to bulk-delete in a directory postmaster did not write to", + dir.display() + )); + } + } + for name in &names { + let Some(name_str) = name.to_str() else { + // Every other skip in this loop logs; a foreign file with a non-UTF8 name + // must not persist silently. + crate::server::log(&format!( + "{}: prune: skipping non-UTF8 entry name", + dir.display() + )); + continue; + }; + // The sentinel is infrastructure, not a secret — never prune it. + if name_str == MANAGED_SENTINEL || keep.contains(name_str) { + continue; + } + // Only unlink regular files; skip subdirectories and symlinks to + // avoid following attacker-controlled links in a shared dir. Both + // the stat (SYMLINK_NOFOLLOW) and the unlink are relative to the + // pinned dir fd, so a swapped entry cannot redirect either one. + let path = dir.join(name); + match rustix::fs::statat(dir_fd, name, rustix::fs::AtFlags::SYMLINK_NOFOLLOW) { + Ok(stat) if rustix::fs::FileType::from_raw_mode(stat.st_mode).is_file() => { + if let Err(e) = rustix::fs::unlinkat(dir_fd, name, rustix::fs::AtFlags::empty()) { + crate::server::log(&format!("{}: prune: {e}", path.display())); + } + } + Ok(stat) => { + crate::server::log(&format!( + "{}: prune: skipping non-file (type {:?})", + path.display(), + rustix::fs::FileType::from_raw_mode(stat.st_mode) + )); + } + Err(e) => { + crate::server::log(&format!("{}: prune: stat: {e}", path.display())); + } + } + } + Ok(()) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic)] +mod tests { + use super::*; + + fn tdir(tag: &str) -> crate::test_util::temp_dir::TestDir { + let d = crate::test_util::temp_dir::TestDir::new(tag); + // prune_stale requires a postmaster-managed (owner-only) dir; match real + // deployments. + use std::os::unix::fs::PermissionsExt; + fs::set_permissions(&d, fs::Permissions::from_mode(0o700)).unwrap(); + d + } + + #[test] + fn env_pairs_rejects_interior_nul() { + let ok = vec![("A".to_string(), Zeroizing::new(b"x\ny".to_vec()))]; + assert_eq!(env_pairs(&ok).unwrap().len(), 1); + let bad = vec![("A".to_string(), Zeroizing::new(b"x\0y".to_vec()))]; + assert!(env_pairs(&bad).unwrap_err().contains("NUL")); + } + + #[test] + fn write_secret_file_writes_0600_via_pinned_fd() { + use std::os::unix::fs::PermissionsExt; + let dir = tdir("write-ok"); + let dir_fd = open_secrets_dir(&dir).unwrap(); + + let path = write_secret_file(&dir_fd, &dir, "KEY", b"plaintext").unwrap(); + + assert_eq!(fs::read(&path).unwrap(), b"plaintext"); + assert_eq!( + fs::metadata(&path).unwrap().permissions().mode() & 0o777, + 0o600, + "secret file must be owner-only" + ); + assert!( + dir.join(MANAGED_SENTINEL).exists(), + "the write drops the managed-dir sentinel (A19)" + ); + } + + #[test] + fn write_secret_file_refuses_symlink() { + let dir = tdir("symlink"); + // A persistent-disk target that must never receive the plaintext. + let real_target = dir.join("real-target"); + fs::write(&real_target, b"untouched").unwrap(); + // Attacker-planted symlink at the path write_secret_file will target. + let link_path = dir.join("KEY"); + std::os::unix::fs::symlink(&real_target, &link_path).unwrap(); + + let dir_fd = open_secrets_dir(&dir).unwrap(); + let result = write_secret_file(&dir_fd, &dir, "KEY", b"attacker-controlled-plaintext"); + + assert!( + result.is_err(), + "write_secret_file must refuse to follow a symlink at the target path" + ); + assert_eq!( + fs::read(&real_target).unwrap(), + b"untouched", + "the symlink's target file must not be written to" + ); + } + + #[test] + fn refresh_does_not_write_to_old_handles_or_linked_inodes() { + use std::io::Read as _; + use std::os::unix::fs::MetadataExt as _; + let dir = tdir("refresh"); + let fd = open_secrets_dir(&dir).unwrap(); + let path = write_secret_file(&fd, &dir, "KEY", b"old").unwrap(); + let old_inode = fs::metadata(&path).unwrap().ino(); + let mut old_handle = fs::File::open(&path).unwrap(); + write_secret_file(&fd, &dir, "KEY", b"new").unwrap(); + assert_ne!(old_inode, fs::metadata(&path).unwrap().ino()); + let mut old = Vec::new(); + old_handle.read_to_end(&mut old).unwrap(); + assert_eq!(old, b"old"); + assert_eq!(fs::read(&path).unwrap(), b"new"); + fs::hard_link(&path, dir.join("LINK")).unwrap(); + assert!(write_secret_file(&fd, &dir, "KEY", b"never").is_err()); + assert_eq!(fs::read(dir.join("LINK")).unwrap(), b"new"); + assert!( + !read_dir_names(&fd) + .unwrap() + .iter() + .any(|n| n.to_string_lossy().starts_with(".postmaster-") && n != MANAGED_SENTINEL) + ); + } + + #[test] + fn special_secret_and_sentinel_files_fail_without_opening() { + let dir = tdir("special"); + let fd = open_secrets_dir(&dir).unwrap(); + assert!( + std::process::Command::new("mkfifo") + .arg(dir.join("KEY")) + .status() + .unwrap() + .success() + ); + assert!(write_secret_file(&fd, &dir, "KEY", b"never").is_err()); + fs::remove_file(dir.join(MANAGED_SENTINEL)).unwrap(); + std::os::unix::fs::symlink(dir.join("target"), dir.join(MANAGED_SENTINEL)).unwrap(); + assert!(write_secret_file(&fd, &dir, "OTHER", b"never").is_err()); + assert!(!dir.join("target").exists()); + } + + #[test] + fn projection_checks_ancestors_and_preserves_sticky_and_trusted_aliases() { + use std::os::unix::fs::PermissionsExt as _; + let dir = tdir("ancestry"); + let shared = dir.join("shared"); + let secret = shared.join("service"); + fs::create_dir_all(&secret).unwrap(); + fs::set_permissions(&shared, fs::Permissions::from_mode(0o777)).unwrap(); + let fd = open_secrets_dir(&secret).unwrap(); + let error = validate_projection(&fd, &secret).unwrap_err(); + let trusted_root = crate::test_util::root_has_trusted_owner(); + if trusted_root { + assert!(error.contains("untrusted replacement"), "{error}"); + } else { + assert_eq!(error, "/: directory path is owned by an untrusted user"); + } + fs::set_permissions(&shared, fs::Permissions::from_mode(0o1777)).unwrap(); + let direct = validate_projection(&fd, &secret); + std::os::unix::fs::symlink(&shared, dir.join("alias")).unwrap(); + let alias = validate_projection(&fd, &dir.join("alias/service")); + if trusted_root { + assert_eq!(direct.unwrap(), secret); + assert_eq!(alias.unwrap(), secret); + write_secret_file(&fd, &secret, "KEY", b"secret").unwrap(); + let child = std::process::Command::new("/bin/sh") + .args(["-c", "cat \"$KEY_FILE\""]) + .env("KEY_FILE", secret.join("KEY")) + .output() + .unwrap(); + assert!(child.status.success()); + assert_eq!(child.stdout, b"secret"); + } else { + assert_eq!(direct.unwrap_err(), error); + assert_eq!(alias.unwrap_err(), error); + assert!(!secret.join("KEY").exists()); + } + } + + #[test] + fn untrusted_user_cannot_replace_exported_sticky_paths_or_receive_refreshes() { + use std::os::unix::fs::PermissionsExt as _; + use std::os::unix::process::CommandExt as _; + if !rustix::process::geteuid().is_root() { + return; + } + let dir = tdir("projection-user"); + fs::set_permissions(&dir, fs::Permissions::from_mode(0o755)).unwrap(); + let shared = dir.join("shared"); + let service = shared.join("service"); + fs::create_dir_all(&service).unwrap(); + fs::set_permissions(&shared, fs::Permissions::from_mode(0o1777)).unwrap(); + let fd = open_secrets_dir(&service).unwrap(); + let projected = validate_projection(&fd, &service).unwrap(); + write_secret_file(&fd, &projected, "KEY", b"protected").unwrap(); + let attempt = std::process::Command::new("/bin/mv") + .arg(&service) + .arg(shared.join("replaced")) + .uid(65534) + .gid(65534) + .output() + .unwrap(); + assert!(!attempt.status.success()); + let child = std::process::Command::new("/bin/sh") + .args([ + "-c", + "test \"$(cat \"$KEY_FILE\")\" = protected && cat \"$CREDENTIALS_DIRECTORY/KEY\"", + ]) + .env("KEY_FILE", projected.join("KEY")) + .env("CREDENTIALS_DIRECTORY", &projected) + .output() + .unwrap(); + assert!(child.status.success()); + assert_eq!(child.stdout, b"protected"); + let foreign = service.join("FOREIGN"); + fs::write(&foreign, b"old").unwrap(); + fs::set_permissions(&foreign, fs::Permissions::from_mode(0o644)).unwrap(); + rustix::fs::chown(&foreign, Some(rustix::fs::Uid::from_raw(65534)), None).unwrap(); + assert!(write_secret_file(&fd, &service, "FOREIGN", b"never").is_err()); + assert_eq!(fs::read(&foreign).unwrap(), b"old"); + assert_eq!( + fs::metadata(&foreign).unwrap().permissions().mode() & 0o777, + 0o644 + ); + } + + #[test] + fn prune_stale_removes_unconfigured_files() { + let dir = tdir("prune"); + // Simulate a previous launch that wrote KEY_A and KEY_B (the + // sentinel marks the directory as managed). + fs::write(dir.join("KEY_A"), b"old-a").unwrap(); + fs::write(dir.join("KEY_B"), b"old-b").unwrap(); + fs::write(dir.join(MANAGED_SENTINEL), b"").unwrap(); + + // New config only keeps KEY_A; KEY_B should be pruned. + prune_stale(&dir, &["KEY_A".to_string()]).unwrap(); + + assert!(dir.join("KEY_A").exists(), "KEY_A should survive prune"); + assert!(!dir.join("KEY_B").exists(), "KEY_B should be pruned"); + assert!( + dir.join(MANAGED_SENTINEL).exists(), + "sentinel is never pruned" + ); + } + + #[test] + fn prune_stale_refuses_unmanaged_dir() { + // A non-empty dir without the sentinel was never written by postmaster; bulk + // deletes could hit foreign files. + let dir = tdir("prune-unmanaged"); + fs::write(dir.join("FOREIGN"), b"not-ours").unwrap(); + + let err = prune_stale(&dir, &[]).unwrap_err(); + + assert!(err.contains("sentinel"), "{err}"); + assert!(dir.join("FOREIGN").exists(), "nothing may be deleted"); + } + + #[test] + fn prune_stale_refuses_symlinked_dir() { + // A symlink swapped in at the secrets-dir path itself must be + // rejected at open (O_DIRECTORY|O_NOFOLLOW), never traversed. + let dir = tdir("prune-symlinked"); + let real = dir.join("real"); + fs::create_dir(&real).unwrap(); + fs::write(real.join("FOREIGN"), b"not-ours").unwrap(); + let link = dir.join("link"); + std::os::unix::fs::symlink(&real, &link).unwrap(); + + let err = prune_stale(&link, &[]).unwrap_err(); + + assert!(err.contains("refusing"), "{err}"); + assert!(real.join("FOREIGN").exists(), "nothing may be deleted"); + } + + #[test] + fn prune_stale_empty_dir_needs_no_sentinel() { + // First launch: the secrets dir exists but is empty — nothing to + // prune, no sentinel required. + let dir = tdir("prune-empty"); + prune_stale(&dir, &[]).unwrap(); + } + + #[test] + fn prune_stale_skips_non_files_and_missing_dir() { + let dir = tdir("prune-nonfile"); + // A subdirectory should be skipped, not unlinked. + fs::create_dir(dir.join("subdir")).unwrap(); + // A file that is kept should survive. + fs::write(dir.join("KEEP_ME"), b"data").unwrap(); + // A symlink is skipped too — prune never follows links in a + // shared dir. + std::os::unix::fs::symlink(dir.join("KEEP_ME"), dir.join("a-link")).unwrap(); + fs::write(dir.join(MANAGED_SENTINEL), b"").unwrap(); + + prune_stale(&dir, &["KEEP_ME".to_string()]).unwrap(); + assert!(dir.join("KEEP_ME").exists()); + assert!(dir.join("subdir").is_dir(), "subdir should not be removed"); + assert!( + fs::symlink_metadata(dir.join("a-link")) + .unwrap() + .file_type() + .is_symlink(), + "symlink should be skipped, not unlinked" + ); + + // Non-existent directory: no error, nothing to prune. + let ghost = dir.join("does-not-exist"); + assert!(prune_stale(&ghost, &["X".to_string()]).is_ok()); + } + + #[test] + fn cleanup_written_unlinks_files() { + let dir = tdir("cleanup"); + let f1 = dir.join("A"); + let f2 = dir.join("B"); + fs::write(&f1, b"secret-a").unwrap(); + fs::write(&f2, b"secret-b").unwrap(); + let dir_fd = open_secrets_dir(&dir).unwrap(); + + // A name that does not exist is ignored (best-effort). + cleanup_written( + &dir_fd, + &["A".to_string(), "B".to_string(), "MISSING".to_string()], + ); + + assert!(!f1.exists(), "cleanup should unlink f1"); + assert!(!f2.exists(), "cleanup should unlink f2"); + } +} diff --git a/src/secret_files/acl.rs b/src/secret_files/acl.rs new file mode 100644 index 0000000..8dd6ef0 --- /dev/null +++ b/src/secret_files/acl.rs @@ -0,0 +1,204 @@ +//! Darwin extended ACL checks; POSIX mode bits alone do not describe access. + +use std::ffi::{c_int, c_void}; +use std::os::fd::{AsFd, AsRawFd as _}; + +const EXTENDED: c_int = 0x100; +const ALLOW: c_int = 1; +const FILE_INHERIT: c_int = 1 << 5; +// sys/acl.h: add file/subdirectory, delete, delete child, write attributes/security, change owner. +const MUTATE: u64 = + (1 << 2) | (1 << 4) | (1 << 5) | (1 << 6) | (1 << 8) | (1 << 10) | (1 << 12) | (1 << 13); + +unsafe extern "C" { + fn acl_get_fd_np(fd: c_int, kind: c_int) -> *mut c_void; + fn acl_init(count: c_int) -> *mut c_void; + fn acl_set_fd_np(fd: c_int, acl: *mut c_void, kind: c_int) -> c_int; + fn acl_free(value: *mut c_void) -> c_int; + fn acl_get_entry(acl: *mut c_void, index: c_int, entry: *mut *mut c_void) -> c_int; + fn acl_get_tag_type(entry: *mut c_void, tag: *mut c_int) -> c_int; + fn acl_get_permset_mask_np(entry: *mut c_void, mask: *mut u64) -> c_int; + fn acl_get_qualifier(entry: *mut c_void) -> *mut c_void; + fn acl_get_flagset_np(entry: *mut c_void, flags: *mut *mut c_void) -> c_int; + fn acl_get_flag_np(flags: *mut c_void, flag: c_int) -> c_int; + fn mbr_uid_to_uuid(uid: u32, uuid: *mut u8) -> c_int; +} + +struct Allocation(*mut c_void); + +impl Drop for Allocation { + fn drop(&mut self) { + // SAFETY: owned allocations returned by the ACL API are released exactly once. + unsafe { + acl_free(self.0); + } + } +} + +/// Clear inherited extended grants before writing plaintext to a fresh inode. +pub(super) fn clear(fd: impl AsFd) -> Result<(), String> { + // SAFETY: live fd and owned ACL storage; the API copies the ACL before storage is freed. + unsafe { + let acl = Allocation(acl_init(0)); + if acl.0.is_null() { + return Err("cannot allocate empty ACL".into()); + } + if acl_set_fd_np(fd.as_fd().as_raw_fd(), acl.0, EXTENDED) != 0 { + let e = std::io::Error::last_os_error(); + if e.raw_os_error() != Some(libc::ENOTSUP) { + return Err(format!("cannot clear file ACL: {e}")); + } + } + } + Ok(()) +} + +/// Reject extended grants that let another principal replace directory entries. +pub(super) fn validate(fd: impl AsFd) -> Result<(), String> { + validate_grants(fd, MUTATE, true) +} + +/// Reject untrusted access to private file contents without changing its ACL. +pub(super) fn validate_private_file(fd: impl AsFd) -> Result<(), String> { + validate_grants(fd, MUTATE | (1 << 1), false) +} + +fn validate_grants(fd: impl AsFd, forbidden: u64, check_inheritance: bool) -> Result<(), String> { + // SAFETY: every out pointer is initialized storage, entry pointers borrow the live ACL, + // and qualifiers are owned UUID allocations with the platform's fixed 16-byte layout. + unsafe { + let acl = Allocation(acl_get_fd_np(fd.as_fd().as_raw_fd(), EXTENDED)); + if acl.0.is_null() { + let e = std::io::Error::last_os_error(); + // Darwin reports ENOENT when a live inode has no extended ACL. + return if matches!(e.raw_os_error(), Some(libc::ENOTSUP | libc::ENOENT)) { + Ok(()) + } else { + Err(format!("cannot read ACL: {e}")) + }; + } + let mut root = [0; 16]; + let mut user = [0; 16]; + if mbr_uid_to_uuid(0, root.as_mut_ptr()) != 0 + || mbr_uid_to_uuid(rustix::process::geteuid().as_raw(), user.as_mut_ptr()) != 0 + { + return Err("cannot resolve trusted ACL principals".into()); + } + for index in 0..=1024 { + let mut entry = std::ptr::null_mut(); + if acl_get_entry(acl.0, index, &mut entry) != 0 { + let e = std::io::Error::last_os_error(); + return if e.raw_os_error() == Some(libc::EINVAL) { + Ok(()) + } else { + Err(format!("cannot read ACL entry: {e}")) + }; + } + if index == 1024 { + return Err("ACL has too many entries".into()); + } + let mut tag = 0; + let mut permissions = 0; + if acl_get_tag_type(entry, &mut tag) != 0 + || acl_get_permset_mask_np(entry, &mut permissions) != 0 + { + return Err("cannot inspect ACL permissions".into()); + } + if tag != ALLOW { + continue; + } + let mut flags = std::ptr::null_mut(); + if check_inheritance && acl_get_flagset_np(entry, &mut flags) != 0 { + return Err("cannot inspect ACL inheritance".into()); + } + let inherited = if check_inheritance { + acl_get_flag_np(flags, FILE_INHERIT) + } else { + 0 + }; + if inherited < 0 { + return Err("cannot inspect ACL inheritance".into()); + } + // An inherited grant can expose a fresh inode before its ACL is cleared. + if permissions & forbidden == 0 && !(inherited == 1 && permissions & (1 << 1) != 0) { + continue; + } + let qualifier = Allocation(acl_get_qualifier(entry)); + if qualifier.0.is_null() { + return Err("cannot read ACL principal".into()); + } + let uuid = std::slice::from_raw_parts(qualifier.0.cast::(), 16); + if uuid != root && uuid != user { + return Err(if check_inheritance { + "directory ACL permits untrusted replacement" + } else { + "private file ACL permits untrusted access" + } + .into()); + } + } + } + Ok(()) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::panic)] +mod tests { + use super::*; + + #[test] + fn extended_grants_cannot_replace_paths_or_reach_new_plaintext() { + let dir = crate::test_util::temp_dir::TestDir::new("acl"); + let fd = crate::secret_files::open_secrets_dir(&dir).unwrap(); + assert!( + std::process::Command::new("/bin/chmod") + .args(["+a", "everyone allow add_file,delete_child"]) + .arg(&*dir) + .status() + .unwrap() + .success() + ); + assert!(validate(&fd).unwrap_err().contains("untrusted replacement")); + assert!( + std::process::Command::new("/bin/chmod") + .arg("-N") + .arg(&*dir) + .status() + .unwrap() + .success() + ); + assert!( + std::process::Command::new("/bin/chmod") + .args(["+a", "everyone allow read,file_inherit"]) + .arg(&*dir) + .status() + .unwrap() + .success() + ); + assert!(validate(&fd).is_err()); + assert!(crate::secret_files::write_secret_file(&fd, &dir, "KEY", b"private").is_err()); + assert!( + std::process::Command::new("/bin/chmod") + .arg("-N") + .arg(&*dir) + .status() + .unwrap() + .success() + ); + validate(&fd).unwrap(); + crate::secret_files::write_secret_file(&fd, &dir, "KEY", b"private").unwrap(); + let file = std::fs::File::open(dir.join("KEY")).unwrap(); + // SAFETY: the returned owned ACL remains live while its first entry is queried. + unsafe { + let acl = Allocation(acl_get_fd_np(file.as_raw_fd(), EXTENDED)); + if !acl.0.is_null() { + let mut entry = std::ptr::null_mut(); + assert_eq!(acl_get_entry(acl.0, 0, &mut entry), -1); + assert_eq!( + std::io::Error::last_os_error().raw_os_error(), + Some(libc::EINVAL) + ); + } + } + } +} diff --git a/src/server.rs b/src/server.rs index 93e9f4b..e92ac7f 100644 --- a/src/server.rs +++ b/src/server.rs @@ -3,8 +3,6 @@ //! This module contains the bulk of the runtime behavior while keeping //! main.rs thin. -#![allow(missing_docs, missing_debug_implementations)] - use std::fs; use std::io::{Read, Write}; use std::net::Shutdown; @@ -25,17 +23,32 @@ use crate::adapter::KeyNaming; use crate::config::{Args, Config, Entry, KeysSource}; use crate::keys::{KeyRing, resolve}; -const WRITE_TIMEOUT: Duration = Duration::from_secs(5); +/// Shared I/O deadline for socket reads and writes (one constant, so +/// the two directions can't silently diverge). +const IO_TIMEOUT: Duration = Duration::from_secs(5); #[cfg(target_os = "linux")] const SD_LISTEN_FDS_START: RawFd = 3; // stderr IS the daemon's log transport (journald on Linux, launchd // StandardErrorPath on darwin) — this is the one sanctioned print site. +/// Log a message to stderr (journald on Linux, launchd on macOS). #[allow(clippy::print_stderr)] pub fn log(msg: &str) { eprintln!("postmaster: {msg}"); } +/// Serve a single credential entry on a Unix socket. Handles one peer +/// at a time (thread-per-socket); each peer must be uid 0 (root) or the +/// configured peer_user. +/// +/// Connection limiting (documented decision): the +/// loop is serialized — one connection at a time, each accepted stream +/// closed at the end of its iteration, writes bounded by IO_TIMEOUT — +/// so per-connection FDs/threads never accumulate and pending connects +/// are bounded by the kernel backlog. A trusted peer (root or the +/// configured peer_user) can starve the listener with slow connections; +/// that is the authorized consumer of this socket, so no rate limiting +/// is implemented. pub fn serve( listener: UnixListener, path: PathBuf, @@ -52,7 +65,10 @@ pub fn serve( continue; } }; - if !allow_nonroot { + // Peer ACL: a configured peer_user is ALWAYS enforced — --allow-nonroot widens + // root→configured-user, never root→anyone. The flag skips verification only + // when no peer_user is configured (the dev loop it exists for). + if !allow_nonroot || peer_uid.is_some() { match peer_euid(&stream) { Ok(0) => {} Ok(uid) if peer_uid == Some(uid) => {} @@ -66,7 +82,7 @@ pub fn serve( } } } - let _ = stream.set_write_timeout(Some(WRITE_TIMEOUT)); + let _ = stream.set_write_timeout(Some(IO_TIMEOUT)); // Fresh resolution per request: rotation-friendly, nothing cached. match resolve(&entry, &ring, KeyNaming::Env) { Ok(value) => { @@ -86,16 +102,38 @@ pub fn serve( } } -/// Connect, read one credential to EOF. Zero bytes means the server -/// refused to serve — fail closed, exactly like LoadCredential failing. -pub fn fetch_bytes(path: &Path) -> Result>, String> { - let mut stream = - UnixStream::connect(path).map_err(|e| format!("{}: connect: {e}", path.display()))?; - let _ = stream.set_read_timeout(Some(WRITE_TIMEOUT)); +/// Maximum bytes accepted for a credential fetch payload, bundle JSON, or config +/// read. These payloads are small; the cap keeps a hostile or broken +/// peer from forcing unbounded heap allocation. Oversized payloads fail. +const MAX_READ_BYTES: u64 = 16 * 1024 * 1024; + +/// Read `reader` to EOF with a hard size cap. +/// Fails rather than truncates when the stream exceeds the cap — a +/// truncated secret must never be served as if complete. +pub(crate) fn read_capped(reader: R, path: &Path) -> Result, String> { + let mut limited = reader.take(MAX_READ_BYTES + 1); let mut buf = Zeroizing::new(Vec::new()); - stream + limited .read_to_end(&mut buf) .map_err(|e| format!("{}: read: {e}", path.display()))?; + if buf.len() as u64 > MAX_READ_BYTES { + return Err(format!( + "{}: exceeds the {}-byte size cap", + path.display(), + MAX_READ_BYTES + )); + } + Ok(std::mem::take(&mut *buf)) +} + +/// Connect, read one credential to EOF (hard-capped by `read_capped`). +/// Zero bytes means the server refused to serve — fail closed, exactly +/// like LoadCredential failing. +pub fn fetch_bytes(path: &Path) -> Result>, String> { + let stream = + UnixStream::connect(path).map_err(|e| format!("{}: connect: {e}", path.display()))?; + let _ = stream.set_read_timeout(Some(IO_TIMEOUT)); + let buf = Zeroizing::new(read_capped(stream, path)?); if buf.is_empty() { return Err(format!( "{}: server sent zero bytes (refused to serve); failing closed", @@ -105,8 +143,8 @@ pub fn fetch_bytes(path: &Path) -> Result>, String> { Ok(buf) } -/// Client half for platforms without LoadCredential (darwin wrappers): -/// connect, read one credential to EOF, emit on stdout. Zero bytes means +/// Connect to a local credential socket, read to EOF, and write to stdout. +/// Available on Linux and macOS. Zero bytes means /// the server refused to serve — fail closed, exactly like LoadCredential /// failing the unit. pub fn fetch(path: &Path) -> Result<(), String> { @@ -157,48 +195,85 @@ fn peer_euid(stream: &UnixStream) -> std::io::Result { Ok(euid) } +/// Attempt to disable dumps and peer tracing and lock memory on Linux. +/// Failures are logged. Dumpability and memory locks reset across exec. #[cfg(target_os = "linux")] pub fn harden_process() { - // No core dumps, no ptrace from non-privileged peers. - let _ = rustix::process::set_dumpable_behavior(rustix::process::DumpableBehavior::NotDumpable); + // No core dumps, no ptrace from non-privileged peers. Best-effort by policy, but a + // failure is security-relevant — log it. + if let Err(e) = + rustix::process::set_dumpable_behavior(rustix::process::DumpableBehavior::NotDumpable) + { + log(&format!( + "hardening: set_dumpable(NotDumpable) failed: {e} — core dumps/ptrace not disabled" + )); + } // Best effort: keep key material off swap even without the unit-level - // MemorySwapMax=0 belt (may fail under RLIMIT_MEMLOCK; that's fine). - let _ = rustix::mm::mlockall( - rustix::mm::MlockAllFlags::CURRENT | rustix::mm::MlockAllFlags::FUTURE, - ); + // MemorySwapMax=0 belt (may fail under RLIMIT_MEMLOCK; that's fine — + // but say so). + if let Err(e) = + rustix::mm::mlockall(rustix::mm::MlockAllFlags::CURRENT | rustix::mm::MlockAllFlags::FUTURE) + { + log(&format!( + "hardening: mlockall failed: {e} — decrypted secrets may swap to disk (check RLIMIT_MEMLOCK)" + )); + } } +/// Attempt to disable core dumps and, in release builds, peer tracing on macOS. +/// Failures are logged. #[cfg(target_os = "macos")] pub fn harden_process() { - // Closest analog to PR_SET_DUMPABLE for dumps: no core files, ever. - let _ = rustix::process::setrlimit( + // Closest analog to PR_SET_DUMPABLE for dumps: no core files, ever. Best-effort by + // policy, but failures are security-relevant — log them. + if let Err(e) = rustix::process::setrlimit( rustix::process::Resource::Core, rustix::process::Rlimit { current: Some(0), maximum: Some(0), }, - ); + ) { + log(&format!( + "hardening: setrlimit(Core, 0) failed: {e} — core dumps not disabled" + )); + } // macOS has no mlockall(2); its swap is encrypted by default, so pages // that do swap out are ciphertext at rest. Deny debugger attach in // release builds (the ptrace-from-peers half of PR_SET_DUMPABLE). #[cfg(not(debug_assertions))] - // SAFETY: PT_DENY_ATTACH takes no pointer arguments; null addr and zero - // data are the documented invocation. - unsafe { - libc::ptrace(libc::PT_DENY_ATTACH, 0, std::ptr::null_mut(), 0); + { + // SAFETY: PT_DENY_ATTACH takes no pointer arguments; null addr and + // zero data are the documented invocation. + let rc = unsafe { libc::ptrace(libc::PT_DENY_ATTACH, 0, std::ptr::null_mut(), 0) }; + if rc != 0 { + let err = std::io::Error::last_os_error(); + log(&format!( + "hardening: PT_DENY_ATTACH failed: {err} — debugger attach not denied" + )); + } } } /// Resolve a user name to a uid without getpwnam FFI. pub fn uid_of(name: &str) -> Result { + // Trust boundary: a compromised `id` returning a wrong uid would defeat the socket + // peer-uid ACL. macOS invokes /usr/bin/id by absolute path under SIP, verified via + // codesign. Linux never uses PATH resolution — a PATH-resolved `id` would inherit a + // potentially attacker-controlled PATH; instead the first candidate absolute path + // that verifies (regular file, root-owned, no group/other write bits — checked by + // fstat on an O_NOFOLLOW|CLOEXEC fd) is invoked, and if none verifies the lookup + // fails closed. #[cfg(target_os = "macos")] - const ID: &str = "/usr/bin/id"; + let id = { + crate::keys::verify_external_binary(Path::new("/usr/bin/id"))?; + PathBuf::from("/usr/bin/id") + }; #[cfg(not(target_os = "macos"))] - const ID: &str = "id"; - let out = std::process::Command::new(ID) + let id = verified_id_binary()?; + let out = std::process::Command::new(&id) .args(["-u", name]) .output() - .map_err(|e| format!("{ID}: {e}"))?; + .map_err(|e| format!("{}: {e}", id.display()))?; if !out.status.success() { return Err(format!("peer_user {name:?}: no such user")); } @@ -208,9 +283,70 @@ pub fn uid_of(name: &str) -> Result { .map_err(|_| format!("peer_user {name:?}: `id -u` output not a uid")) } +/// First `id(1)` candidate that exists and verifies, or a fail-closed +/// error listing why each was rejected (Linux only — see `uid_of`). +/// Candidates are well-known absolute paths in preference order; the +/// NixOS path covers systems without /usr/bin or /bin. +#[cfg(not(target_os = "macos"))] +fn verified_id_binary() -> Result { + const CANDIDATES: [&str; 3] = ["/usr/bin/id", "/bin/id", "/run/current-system/sw/bin/id"]; + let mut failures: Vec = Vec::new(); + for path in CANDIDATES { + match verify_id_candidate(path) { + Ok(target) => return Ok(target), + Err(e) => failures.push(e), + } + } + Err(format!( + "no trustworthy `id` binary found (refusing PATH resolution; tried {}): {}", + CANDIDATES.join(", "), + failures.join("; ") + )) +} + +/// Resolve a system alias, verify its protected target by opened fd, and return +/// that target for invocation. The final open uses O_NOFOLLOW|CLOEXEC. +/// The target must be a regular file owned by root with no group/other write +/// bits. Type, owner and mode are checked on the same opened inode. +#[cfg(not(target_os = "macos"))] +fn verify_id_candidate(path: &str) -> Result { + let target = fs::canonicalize(path).map_err(|e| format!("{path}: resolve: {e}"))?; + crate::secret_files::validate_directory_path( + target.parent().ok_or("id requires a parent directory")?, + )?; + let fd = rustix::fs::open( + &target, + rustix::fs::OFlags::RDONLY | rustix::fs::OFlags::NOFOLLOW | rustix::fs::OFlags::CLOEXEC, + rustix::fs::Mode::empty(), + ) + .map_err(|e| format!("{path}: {e}"))?; + let stat = rustix::fs::fstat(&fd).map_err(|e| format!("{path}: fstat: {e}"))?; + if !rustix::fs::FileType::from_raw_mode(stat.st_mode).is_file() { + return Err(format!("{path}: not a regular file")); + } + if stat.st_uid != 0 { + return Err(format!( + "{path}: owned by uid {} (expected root/0); refusing to trust", + stat.st_uid + )); + } + if rustix::fs::Mode::from_bits_truncate(stat.st_mode) + .intersects(rustix::fs::Mode::WGRP | rustix::fs::Mode::WOTH) + { + return Err(format!("{path}: group/other writable; refusing to trust")); + } + Ok(target) +} + +/// Resolve the keys file path from a `KeysSource` configuration. pub fn keys_path(source: &KeysSource) -> Result { match source { KeysSource::Credential(name) => { + // Same discipline as the exec-config credential source: the name must be a + // single relative path component — otherwise "../../…" would escape + // $CREDENTIALS_DIRECTORY and read an arbitrary root-readable file as key + // material. + crate::exec_config::validate_credential_source_name(name)?; let dir = std::env::var_os("CREDENTIALS_DIRECTORY").ok_or( "keys.credential configured but $CREDENTIALS_DIRECTORY is unset \ (is LoadCredential wired on the postmaster unit?)", @@ -229,56 +365,166 @@ pub fn keys_path(source: &KeysSource) -> Result { } } +/// RAII guard that sets the process umask so a bound unix socket is born +/// with `mode` (sockets are created `0777 & ~umask`) and restores the +/// prior mask on drop. Used only during single-threaded socket setup. +#[derive(Debug)] +struct UmaskGuard(rustix::fs::Mode); + +impl UmaskGuard { + fn around_bind(mode: rustix::fs::Mode) -> Self { + let mask = !mode & rustix::fs::Mode::from_bits_truncate(0o777); + Self(rustix::process::umask(mask)) + } +} + +impl Drop for UmaskGuard { + fn drop(&mut self) { + rustix::process::umask(self.0); + } +} + +struct SocketDomain { + parent: PathBuf, + traversed: std::collections::HashSet, + uid: u32, +} + +/// Resolve aliases while retaining each directory traversed by the consumer's pathname. +fn socket_domain(path: &Path, uid: u32) -> Result { + let mut resolved = PathBuf::new(); + let mut traversed = std::collections::HashSet::new(); + for part in path + .parent() + .ok_or("socket requires a parent directory")? + .components() + { + if part == std::path::Component::ParentDir { + resolved.pop(); + continue; + } + resolved.push(part); + match fs::canonicalize(&resolved) { + Ok(path) => resolved = path, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => {} + Err(e) => return Err(format!("{}: socket parent: {e}", path.display())), + } + traversed.extend(resolved.ancestors().map(Path::to_path_buf)); + } + Ok(SocketDomain { + parent: resolved, + traversed, + uid, + }) +} + +/// Reject ownership domains where one consumer could replace another's sockets. +fn validate_socket_domains( + cfg: &Config, + peer_uids: &std::collections::HashMap>, + euid: u32, +) -> Result<(), String> { + let mut domains: Vec = Vec::new(); + for path in cfg.credentials.keys() { + let uid = if euid == 0 { + peer_uids.get(path).copied().flatten().unwrap_or(0) + } else { + euid + }; + let domain = socket_domain(path, uid)?; + for other in &domains { + let same = domain.parent == other.parent; + let controlled = other.uid != 0 && domain.traversed.contains(&other.parent) + || uid != 0 && other.traversed.contains(&domain.parent); + if uid != other.uid && (same || controlled) { + return Err(format!( + "{} and {}: socket parents have conflicting ownership domains", + domain.parent.display(), + other.parent.display() + )); + } + } + domains.push(domain); + } + Ok(()) +} + +/// Bind and listen on all configured credential sockets. Returns +/// a vector of `(UnixListener, path)` pairs ready for serving (the entry +/// is re-looked-up by the caller). +/// Call during single-threaded startup: bind mode temporarily changes umask. pub fn acquire_listeners( cfg: &Config, bind: bool, peer_uids: &std::collections::HashMap>, ) -> Result, String> { - use std::os::fd::AsFd; if bind { + validate_socket_domains(cfg, peer_uids, rustix::process::geteuid().as_raw())?; let am_root = rustix::process::geteuid().is_root(); let mut out = Vec::new(); for path in cfg.credentials.keys() { let expected = peer_uids.get(path).copied().flatten(); if let Some(parent) = path.parent() { + // Refuse a symlinked socket parent unconditionally in bind mode: + // create_dir_all, remove_file, and bind all follow a swapped parent, + // and the O_NOFOLLOW fd discipline below only runs when privileged with + // a configured peer_user. + match fs::symlink_metadata(parent) { + Ok(md) if md.file_type().is_symlink() => { + return Err(format!( + "{}: socket parent is a symlink; refusing to follow", + parent.display() + )); + } + Ok(_) => {} + Err(e) if e.kind() == std::io::ErrorKind::NotFound => {} + Err(e) => { + return Err(format!( + "{}: cannot stat socket parent: {e}", + parent.display() + )); + } + } fs::create_dir_all(parent).map_err(|e| format!("{}: {e}", parent.display()))?; // The parent directory is the filesystem half of the ACL: // owned by the consumer's user, execute-only-for-owner, so // only that user (and root) can even reach the socket. Only // meaningful when we run privileged; dev runs skip it. if am_root && let Some(uid) = expected { - rustix::fs::chown(parent, Some(rustix::fs::Uid::from_raw(uid)), None) - .map_err(|e| format!("{}: chown: {e}", parent.display()))?; - // Audit finding #6: use fchmod on the directory fd - // instead of set_permissions on the path to eliminate a - // TOCTOU between chown and chmod. Open the directory - // read-only with O_DIRECTORY, fchmod the fd, close. + // Open the directory and operate on the fd throughout: O_NOFOLLOW + // rejects a symlink at the final component, and fchown/fchmod on + // the fd act on the pinned inode, immune to path swaps. let dir_fd = rustix::fs::open( parent, rustix::fs::OFlags::RDONLY | rustix::fs::OFlags::DIRECTORY + | rustix::fs::OFlags::NOFOLLOW | rustix::fs::OFlags::CLOEXEC, rustix::fs::Mode::empty(), ) - .map_err(|e| format!("{}: open dir: {e}", parent.display()))?; + .map_err(|e| { + format!( + "{}: open dir: {e} (refusing to follow a symlink)", + parent.display() + ) + })?; + rustix::fs::fchown(&dir_fd, Some(rustix::fs::Uid::from_raw(uid)), None) + .map_err(|e| format!("{}: fchown: {e}", parent.display()))?; rustix::fs::fchmod(&dir_fd, rustix::fs::Mode::from_bits_truncate(0o500)) .map_err(|e| format!("{}: fchmod: {e}", parent.display()))?; } } let _ = fs::remove_file(path); - let l = - UnixListener::bind(path).map_err(|e| format!("{}: bind: {e}", path.display()))?; // connect(2) needs write on the socket inode; the reachability // gate is the 0500 parent dir plus the peer-credential check. let mode = if expected.is_some() { 0o666 } else { 0o600 }; - // Audit finding #7: use fchmod on the socket fd instead of - // set_permissions on the path to eliminate a TOCTOU between - // bind and chmod. Between those two path operations an attacker - // with directory write access could unlink the socket and - // create a symlink. fchmod operates on the already-bound fd, - // which is the socket inode we just created. - rustix::fs::fchmod(l.as_fd(), rustix::fs::Mode::from_bits_truncate(mode)) - .map_err(|e| format!("{}: fchmod: {e}", path.display()))?; + // fchmod on Linux changes the sockfs inode, not the pathname; + // Darwin rejects it. Bind with the final mode to avoid a chmod race. + let l = { + let _umask_guard = + UmaskGuard::around_bind(rustix::fs::Mode::from_bits_truncate(mode)); + UnixListener::bind(path).map_err(|e| format!("{}: bind: {e}", path.display()))? + }; out.push((l, path.clone())); } return Ok(out); @@ -304,7 +550,7 @@ pub fn acquire_listeners( let mut seen: Vec = Vec::new(); let mut out = Vec::new(); for fd in fds { - // SAFETY: the sole unsafe in the program. sd_listen_fds() proved + // SAFETY: sd_listen_fds() proved // LISTEN_PID names this process, so fds [3, 3+n) are listening // sockets systemd created for us and nothing else owns them; taking // ownership here is exactly the sd_listen_fds(3) contract. @@ -339,23 +585,51 @@ pub fn acquire_listeners( } } -pub fn run(args: &Args) -> Result<(), String> { - let raw = fs::read(&args.config).map_err(|e| format!("{}: {e}", args.config.display()))?; - let cfg: Config = - serde_json::from_slice(&raw).map_err(|e| format!("{}: {e}", args.config.display()))?; - if cfg.credentials.is_empty() { - return Err("config maps no credentials; nothing to do".into()); +/// Enforce the absoluteness the config type docs promise: a CWD-relative +/// socket or keys path would resolve against whatever directory the +/// daemon happened to start in. +fn validate_absolute_paths(cfg: &Config) -> Result<(), String> { + for path in cfg.credentials.keys() { + if !path.is_absolute() { + return Err(format!( + "{}: socket path must be absolute (fail closed)", + path.display() + )); + } } + if let KeysSource::File(p) = &cfg.keys + && !p.is_absolute() + { + return Err(format!( + "{}: keys file path must be absolute (fail closed)", + p.display() + )); + } + Ok(()) +} - let ring = Arc::new(KeyRing::load(&keys_path(&cfg.keys)?, KeyNaming::Env)?); - - // Preflight: prove every credential is servable — and every peer_user - // resolvable — before accepting anyone. +/// Preflight: prove every credential is servable — and every peer_user +/// resolvable — before accepting anyone. An empty resolved value is +/// unservable (zero bytes means refusal on the wire), so it fails here +/// at startup naming the key rather than leaving +/// the daemon looking healthy while the credential permanently fails +/// with a misdiagnosing message. +fn preflight_credentials( + cfg: &Config, + ring: &KeyRing, +) -> Result>, String> { let mut peer_uids: std::collections::HashMap> = std::collections::HashMap::new(); for (path, entry) in &cfg.credentials { - resolve(entry, &ring, KeyNaming::Env) + let value = resolve(entry, ring, KeyNaming::Env) .map_err(|e| format!("preflight {}: {e}", path.display()))?; + if value.is_empty() { + return Err(format!( + "preflight {}: {} resolved to an empty value, which can never be served (zero bytes means refusal on the wire)", + path.display(), + entry.key + )); + } let uid = entry .peer_user .as_deref() @@ -364,15 +638,55 @@ pub fn run(args: &Args) -> Result<(), String> { .map_err(|e| format!("preflight {}: {e}", path.display()))?; peer_uids.insert(path.clone(), uid); } + Ok(peer_uids) +} + +/// Load keys, bind sockets, and serve credential requests. +/// The caller applies process hardening before calling. Runs until the process is +/// terminated; returns only on startup-path failure. +pub fn run(args: &Args) -> Result<(), String> { + let file = + fs::File::open(&args.config).map_err(|e| format!("{}: {e}", args.config.display()))?; + let raw = read_capped(file, &args.config)?; + let cfg: Config = + serde_json::from_slice(&raw).map_err(|e| format!("{}: {e}", args.config.display()))?; + if cfg.credentials.is_empty() { + return Err("config maps no credentials; nothing to do".into()); + } + validate_absolute_paths(&cfg)?; + + // The daemon's fetch contract is dotenvx-style env entries only; the + // bundle adapter is an exec-mode surface, so the ring requires Env + // naming alone here. + let ring = Arc::new(KeyRing::load(&keys_path(&cfg.keys)?, &[KeyNaming::Env])?); + + let peer_uids = preflight_credentials(&cfg, &ring)?; log(&format!( "preflight ok: {} credential(s) decryptable", cfg.credentials.len() )); + // --allow-nonroot never overrides a configured peer_user; say so once at startup + // when both are present. + if args.allow_nonroot && peer_uids.values().any(Option::is_some) { + log( + "note: --allow-nonroot does not override configured peer_user ACLs — peer_user sockets still verify the connecting uid", + ); + } let listeners = acquire_listeners(&cfg, args.bind, &peer_uids)?; let mut handles = Vec::new(); for (listener, path) in listeners { - let entry = cfg.credentials.get(&path).expect("validated above").clone(); + let entry = match cfg.credentials.get(&path) { + Some(e) => e.clone(), + // Unreachable (listeners derive from cfg.credentials), but a clear error + // beats an abort under panic=abort. + None => { + return Err(format!( + "{}: internal: listener path missing from config", + path.display() + )); + } + }; let peer_uid = peer_uids.get(&path).copied().flatten(); let ring = Arc::clone(&ring); let allow = args.allow_nonroot; @@ -398,9 +712,7 @@ mod tests { #[test] fn fetch_bytes_roundtrip_and_empty_fails_closed() { - let dir = std::env::temp_dir().join(format!("pm-fetch-{}", std::process::id())); - let _ = fs::remove_dir_all(&dir); - fs::create_dir_all(&dir).unwrap(); + let dir = crate::test_util::temp_dir::TestDir::new("server"); let sock = dir.join("t.sock"); let listener = UnixListener::bind(&sock).unwrap(); let t = thread::spawn(move || { @@ -416,4 +728,210 @@ mod tests { assert!(fetch_bytes(&sock).unwrap_err().contains("zero bytes")); t.join().unwrap(); } + + #[test] + #[cfg(not(target_os = "macos"))] + fn verify_id_candidate_rejects_untrusted_file() { + // A user-owned, group/other-writable file must fail: non-root + // runs trip the root-ownership check, root runs trip the + // write-bits check — either way the file is refused. + use std::os::unix::fs::PermissionsExt; + let fixture = crate::test_util::temp_dir::TestDir::new("server"); + let path = fixture.join("fixture"); + fs::write(&path, b"fake id").unwrap(); + fs::set_permissions(&path, fs::Permissions::from_mode(0o666)).unwrap(); + let p = path.to_str().unwrap().to_string(); + + let err = verify_id_candidate(&p).unwrap_err(); + + let _ = fs::remove_file(&path); + if crate::test_util::root_has_trusted_owner() { + assert!( + err.contains("owned by uid") || err.contains("writable"), + "{err}" + ); + } else { + assert_eq!(err, "/: directory path is owned by an untrusted user"); + } + } + + #[test] + #[cfg(not(target_os = "macos"))] + fn verified_id_binary_uses_system_paths_or_fails_closed() { + let paths = ["/usr/bin/id", "/bin/id", "/run/current-system/sw/bin/id"]; + let available = paths.iter().any(|p| Path::new(p).try_exists().unwrap()); + let result = verified_id_binary(); + if available && crate::test_util::root_has_trusted_owner() { + assert!(result.unwrap().is_absolute()); + } else { + let err = result.unwrap_err(); + assert!(err.starts_with("no trustworthy `id` binary found"), "{err}"); + assert!(err.contains("refusing PATH resolution"), "{err}"); + for path in paths { + assert!(err.contains(path), "{err}"); + } + } + } + + #[test] + #[cfg(target_os = "linux")] + fn id_lookup_accepts_trusted_nix_style_aliases() { + use std::os::unix::fs::PermissionsExt as _; + if !rustix::process::geteuid().is_root() { + return; + } + let dir = crate::test_util::temp_dir::TestDir::new("id-alias"); + let target = dir.join("store/bin"); + fs::create_dir_all(&target).unwrap(); + fs::copy(verified_id_binary().unwrap(), target.join("id")).unwrap(); + fs::set_permissions(target.join("id"), fs::Permissions::from_mode(0o755)).unwrap(); + fs::create_dir(dir.join("current-system")).unwrap(); + std::os::unix::fs::symlink(dir.join("store"), dir.join("current-system/sw")).unwrap(); + std::os::unix::fs::symlink("id", target.join("id-link")).unwrap(); + let alias = dir.join("current-system/sw/bin/id-link"); + let verified = verify_id_candidate(alias.to_str().unwrap()).unwrap(); + assert_eq!(verified, target.join("id")); + fs::remove_file(target.join("id-link")).unwrap(); + let out = std::process::Command::new(&verified) + .arg("-u") + .output() + .unwrap(); + assert!(out.status.success()); + assert_eq!(out.stdout, b"0\n"); + fs::set_permissions(&verified, fs::Permissions::from_mode(0o775)).unwrap(); + assert!( + verify_id_candidate(verified.to_str().unwrap()) + .unwrap_err() + .contains("writable") + ); + } + + #[test] + fn preflight_rejects_empty_resolved_value() { + // Zero bytes means refusal on the wire, so an empty value must fail at startup, + // not at first fetch. + let dir = crate::test_util::temp_dir::TestDir::new("server"); + let env_file = dir.join(".env"); + fs::write(&env_file, "KEY=\n").unwrap(); + let mut credentials = std::collections::HashMap::new(); + credentials.insert( + PathBuf::from("/run/postmaster-credd/svc/KEY.sock"), + Entry { + env_file, + key: "KEY".to_string(), + env_file_sha256: vec![{ + use sha2::Digest as _; + sha2::Sha256::digest(b"KEY=\n").into() + }], + peer_user: None, + }, + ); + let cfg = Config { + keys: KeysSource::File(dir.join(".env.keys")), + credentials, + }; + let ring = KeyRing::from_pairs( + [( + "DOTENV_PRIVATE_KEY".to_string(), + Zeroizing::new("11".repeat(32)), + )], + &[KeyNaming::Env], + ) + .unwrap(); + let err = preflight_credentials(&cfg, &ring).unwrap_err(); + assert!(err.contains("empty value"), "{err}"); + let _ = fs::remove_dir_all(&dir); + } + + #[test] + fn validate_absolute_paths_rejects_relative() { + // Socket and keys paths must be absolute. + let mut credentials = std::collections::HashMap::new(); + credentials.insert( + PathBuf::from("relative/key.sock"), + Entry { + env_file: PathBuf::from("/x/.env"), + key: "K".to_string(), + env_file_sha256: Vec::new(), + peer_user: None, + }, + ); + let cfg = Config { + keys: KeysSource::File(PathBuf::from("/abs/.env.keys")), + credentials, + }; + let err = validate_absolute_paths(&cfg).unwrap_err(); + assert!(err.contains("absolute"), "{err}"); + + // The keys-file leg: a relative keys path is caught too. + let cfg2 = Config { + keys: KeysSource::File(PathBuf::from("rel/.env.keys")), + credentials: std::collections::HashMap::new(), + }; + let err = validate_absolute_paths(&cfg2).unwrap_err(); + assert!(err.contains("absolute"), "{err}"); + } + + #[test] + fn read_capped_passes_at_cap_and_fails_over_cap() { + // Accept the exact cap; reject excess bytes rather than serving a truncated secret. + let at_cap = std::io::repeat(0x41).take(MAX_READ_BYTES); + let got = read_capped(at_cap, Path::new("/test")).unwrap(); + assert_eq!(got.len() as u64, MAX_READ_BYTES); + assert!(got.iter().all(|b| *b == 0x41)); + + let over_cap = std::io::repeat(0x41).take(MAX_READ_BYTES + 1); + let err = read_capped(over_cap, Path::new("/test")).unwrap_err(); + assert!(err.contains("size cap"), "{err}"); + } + + #[test] + fn socket_domains_are_checked_before_mutation_including_aliases() { + let dir = crate::test_util::temp_dir::TestDir::new("socket-domains"); + let parent = dir.join("sockets"); + fs::create_dir(&parent).unwrap(); + std::os::unix::fs::symlink(&parent, dir.join("alias")).unwrap(); + fs::create_dir_all(dir.join("outside/sub")).unwrap(); + std::os::unix::fs::symlink(dir.join("outside"), parent.join("escape")).unwrap(); + for second in [ + parent.join("B.sock"), + parent.join("nested/B.sock"), + dir.join("alias/B.sock"), + parent.join("unused/../B.sock"), + parent.join("escape/sub/B.sock"), + ] { + let first = parent.join("A.sock"); + let cfg = Config { + keys: KeysSource::File(dir.join(".env.keys")), + credentials: [first.clone(), second.clone()] + .into_iter() + .map(|p| { + ( + p, + Entry { + env_file: dir.join(".env"), + key: "KEY".into(), + env_file_sha256: Vec::new(), + peer_user: None, + }, + ) + }) + .collect(), + }; + let mut peers = [(first.clone(), Some(1001)), (second.clone(), Some(1002))] + .into_iter() + .collect(); + assert!( + validate_socket_domains(&cfg, &peers, 0) + .unwrap_err() + .contains("conflicting ownership") + ); + assert_eq!(fs::read_dir(&parent).unwrap().count(), 1); + peers.insert(second.clone(), Some(1001)); + validate_socket_domains(&cfg, &peers, 0).unwrap(); + peers.insert(first.clone(), None); + peers.insert(second, Some(0)); + validate_socket_domains(&cfg, &peers, 0).unwrap(); + } + } } diff --git a/src/test_util.rs b/src/test_util.rs new file mode 100644 index 0000000..166b909 --- /dev/null +++ b/src/test_util.rs @@ -0,0 +1,23 @@ +//! Test-only shared utilities (compiled under `#[cfg(test)]` only). + +pub(crate) mod aad_fixture; +pub(crate) mod pty; +pub(crate) mod temp_dir; + +/// Whether `/` is owned by root or the current effective user. +pub(crate) fn root_has_trusted_owner() -> bool { + use std::os::unix::fs::MetadataExt as _; + let owner = std::fs::metadata("/").expect("stat filesystem root").uid(); + owner == 0 || owner == rustix::process::geteuid().as_raw() +} + +/// Process-wide lock serializing every unit test that mutates — or +/// wholesale snapshots — the process-global environment. The test +/// harness runs tests in parallel threads of one process, so +/// unsynchronized `set_var`/`remove_var`, or a full `vars()` scan +/// racing another test's mutation, is a data race; edition 2024 marks +/// those calls `unsafe`. +/// +/// Environment-mutating and whole-environment snapshot tests hold this lock +/// for the full scope. Separate module-local locks would not exclude each other. +pub(crate) static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()); diff --git a/src/test_util/aad_fixture.rs b/src/test_util/aad_fixture.rs new file mode 100644 index 0000000..34c1121 --- /dev/null +++ b/src/test_util/aad_fixture.rs @@ -0,0 +1,26 @@ +//! Test-only AAD envelope construction, independent of the production decoder. +#![allow(clippy::unwrap_used)] + +use aes_gcm::aead::{AeadInOut, KeyInit, Nonce}; +use aes_gcm::{AesGcm, aes::Aes256, aes::cipher::consts::U16}; +use zeroize::Zeroizing; + +/// Encrypt a test value with a fresh ephemeral key and the supplied AAD. +pub fn encrypt(public: &[u8], plaintext: &[u8], aad: &[u8]) -> Vec { + type Cipher = AesGcm; + let public = ecies::PublicKey::parse_slice(public, None).unwrap(); + let (secret, ephemeral) = ecies::utils::generate_keypair(); + let key = Zeroizing::new(ecies::utils::encapsulate(&secret, &public, false).unwrap()); + let cipher = Cipher::new_from_slice(&key[..]).unwrap(); + // Each fixture uses a fresh derived AES key, so this nonce is never reused with a key. + let nonce = Nonce::::default(); + let mut ciphertext = plaintext.to_vec(); + let tag = cipher + .encrypt_inout_detached(&nonce, aad, ciphertext.as_mut_slice().into()) + .unwrap(); + let mut envelope = ephemeral.serialize().to_vec(); + envelope.extend_from_slice(&nonce); + envelope.extend_from_slice(&tag); + envelope.extend_from_slice(&ciphertext); + envelope +} diff --git a/src/test_util/pty.rs b/src/test_util/pty.rs new file mode 100644 index 0000000..6cfbd2e --- /dev/null +++ b/src/test_util/pty.rs @@ -0,0 +1,117 @@ +//! A bounded pseudo-terminal harness for secret-input regression tests. + +#![allow(dead_code, clippy::unwrap_used, clippy::panic)] + +use std::fs::File; +use std::io::{Read as _, Write as _}; +use std::os::fd::FromRawFd as _; +use std::process::{Child, Command, ExitStatus, Stdio}; +use std::time::{Duration, Instant}; + +pub struct TestPty { + master: File, + pub slave: File, + pub output: Vec, + child: Option, +} + +impl TestPty { + pub fn new() -> Self { + let (mut master, mut slave) = (-1, -1); + // SAFETY: valid output pointers; null optional arguments request default settings. + assert_eq!( + unsafe { + libc::openpty( + &mut master, + &mut slave, + std::ptr::null_mut(), + std::ptr::null_mut(), + std::ptr::null_mut(), + ) + }, + 0 + ); + // SAFETY: openpty returned two new descriptors, each transferred once to File. + let (master, slave) = unsafe { (File::from_raw_fd(master), File::from_raw_fd(slave)) }; + Self { + master, + slave, + output: Vec::new(), + child: None, + } + } + + pub fn spawn(&mut self, command: &mut Command) { + self.spawn_with_stderr(command, Stdio::from(self.slave.try_clone().unwrap())); + } + + pub fn spawn_with_stderr(&mut self, command: &mut Command, stderr: Stdio) { + self.child = Some( + command + .stdin(Stdio::from(self.slave.try_clone().unwrap())) + .stdout(Stdio::from(self.slave.try_clone().unwrap())) + .stderr(stderr) + .spawn() + .unwrap(), + ); + } + + pub fn send(&mut self, bytes: &[u8]) { + self.master.write_all(bytes).unwrap(); + } + + fn receive(&mut self) { + let mut fds = [rustix::event::PollFd::new( + &self.master, + rustix::event::PollFlags::IN, + )]; + let timeout = rustix::event::Timespec { + tv_sec: 0, + tv_nsec: 20_000_000, + }; + if rustix::event::poll(&mut fds, Some(&timeout)).unwrap() != 0 { + let mut bytes = [0; 4096]; + if let Ok(count) = self.master.read(&mut bytes) { + self.output.extend_from_slice(&bytes[..count]); + } + } + } + + pub fn expect(&mut self, needle: &str) { + let deadline = Instant::now() + Duration::from_secs(5); + while !String::from_utf8_lossy(&self.output).contains(needle) { + assert!( + Instant::now() < deadline, + "missing {needle:?}: {}", + String::from_utf8_lossy(&self.output) + ); + self.receive(); + } + } + + pub fn signal(&self, signal: rustix::process::Signal) { + let pid = rustix::process::Pid::from_raw(self.child.as_ref().unwrap().id() as i32).unwrap(); + rustix::process::kill_process(pid, signal).unwrap(); + } + + pub fn wait(&mut self) -> ExitStatus { + let deadline = Instant::now() + Duration::from_secs(5); + loop { + self.receive(); + if let Some(status) = self.child.as_mut().unwrap().try_wait().unwrap() { + self.receive(); + return status; + } + assert!(Instant::now() < deadline, "child did not exit"); + } + } +} + +impl Drop for TestPty { + fn drop(&mut self) { + if let Some(child) = &mut self.child { + let _ = child.kill(); + let _ = child.wait(); + } + } +} diff --git a/src/test_util/temp_dir.rs b/src/test_util/temp_dir.rs new file mode 100644 index 0000000..7ba00a6 --- /dev/null +++ b/src/test_util/temp_dir.rs @@ -0,0 +1,43 @@ +//! Private, atomically created test workspaces with scoped cleanup. +#![allow(dead_code, clippy::unwrap_used, clippy::panic)] + +use std::os::unix::fs::PermissionsExt; +use std::path::{Path, PathBuf}; + +/// A private test directory; path access never releases its cleanup guard. +#[derive(Debug)] +pub struct TestDir { + path: PathBuf, + _guard: tempfile::TempDir, +} + +impl TestDir { + /// Create a fresh owner-only workspace, or fail before any fixture writes. + pub fn new(tag: &str) -> Self { + // Short names leave room for Unix socket paths on Darwin. + let guard = tempfile::Builder::new() + .prefix("pm-") + .permissions(std::fs::Permissions::from_mode(0o700)) + .tempdir() + .unwrap_or_else(|e| panic!("test directory ({tag}): {e}")); + let path = std::fs::canonicalize(guard.path()).unwrap(); + Self { + path, + _guard: guard, + } + } +} + +impl std::ops::Deref for TestDir { + type Target = PathBuf; + + fn deref(&self) -> &PathBuf { + &self.path + } +} + +impl AsRef for TestDir { + fn as_ref(&self) -> &Path { + &self.path + } +} diff --git a/tests/common/mod.rs b/tests/common/mod.rs index e65a133..e1360ea 100644 --- a/tests/common/mod.rs +++ b/tests/common/mod.rs @@ -4,6 +4,11 @@ //! fixture verification (README); these helpers guard OUR semantics. #![allow(dead_code, clippy::unwrap_used, clippy::panic, missing_docs)] +#[path = "../../src/test_util/aad_fixture.rs"] +pub mod aad_fixture; +#[path = "../../src/test_util/temp_dir.rs"] +pub mod temp_dir; + use std::fs; use std::path::{Path, PathBuf}; @@ -28,15 +33,8 @@ pub fn enc(value: &str) -> String { format!("encrypted:{}", BASE64.encode(ct)) } -pub fn tmpdir(tag: &str) -> PathBuf { - let d = std::env::temp_dir().join(format!( - "postmaster-exec-{tag}-{}-{:?}", - std::process::id(), - std::thread::current().id() - )); - let _ = fs::remove_dir_all(&d); - fs::create_dir_all(&d).unwrap(); - d +pub fn tmpdir(tag: &str) -> temp_dir::TestDir { + temp_dir::TestDir::new(tag) } pub fn write_env_file(dir: &Path, name: &str, lines: &[String]) -> PathBuf { @@ -57,8 +55,7 @@ pub fn write_keys_file(dir: &Path, env_suffix: &str, sk_hexes: &[&str]) -> PathB }; let p = dir.join(".env.keys"); fs::write(&p, format!("{var}=\"{}\"\n", sk_hexes.join(","))).unwrap(); - // KeyRing::load now enforces 0600-or-stricter permissions and euid - // ownership (audit finding #1). The temp file must pass that check. + // Match the owner-only permissions required by KeyRing::load. fs::set_permissions(&p, fs::Permissions::from_mode(0o600)).unwrap(); p } diff --git a/tests/exec_check.rs b/tests/exec_check.rs index f85be0f..891a7dd 100644 --- a/tests/exec_check.rs +++ b/tests/exec_check.rs @@ -1,9 +1,12 @@ #![allow(clippy::unwrap_used, clippy::panic, missing_docs)] +#[path = "../src/test_util/temp_dir.rs"] +mod temp_dir; + use std::path::{Path, PathBuf}; use std::process::Command; -use postmaster::config::ExecConfig; +use postmaster::exec_config::ExecConfig; fn repo_root() -> PathBuf { Path::new(env!("CARGO_MANIFEST_DIR")).to_path_buf() @@ -13,11 +16,8 @@ fn fixture(path: &str) -> PathBuf { repo_root().join(path) } -fn tmpdir(tag: &str) -> PathBuf { - let d = std::env::temp_dir().join(format!("pm-exec-check-{tag}-{}", std::process::id())); - let _ = std::fs::remove_dir_all(&d); - std::fs::create_dir_all(&d).unwrap(); - d +fn tmpdir(tag: &str) -> temp_dir::TestDir { + temp_dir::TestDir::new(tag) } fn run_check(config: &Path) -> std::process::Output { @@ -44,6 +44,7 @@ fn docs_exec_schema_is_valid_json() { fn docs_exec_examples_parse_and_validate() { for rel in [ "docs/examples/exec-env.json", + "docs/examples/exec-bundle.json", "docs/examples/exec-files.json", "docs/examples/exec-credentials-systemd.json", "docs/examples/exec-credentials-darwin.json", @@ -152,3 +153,37 @@ fn exec_check_rejects_path_like_credential_source_names() { let stderr = String::from_utf8_lossy(&out.stderr); assert!(stderr.contains("credential source"), "stderr: {stderr}"); } + +#[test] +fn docs_exec_schema_covers_every_exec_config_field() { + let raw = std::fs::read(fixture("docs/schema/exec.schema.json")).unwrap(); + let schema: serde_json::Value = serde_json::from_slice(&raw).unwrap(); + let properties = schema + .get("properties") + .and_then(serde_json::Value::as_object) + .unwrap(); + // Keep this list in sync with the fields on `ExecConfig` in + // src/exec_config.rs to catch schema/parser drift. + for field in [ + "mode", + "keys", + "env_files", + "bundle_files", + "strict", + "overload", + "secrets_dir", + "passthrough", + "credential_keys", + "sockets", + "verify_ramdisk", + ] { + assert!( + properties.contains_key(field), + "schema properties missing {field}" + ); + } + assert_eq!( + schema.get("additionalProperties"), + Some(&serde_json::Value::Bool(false)) + ); +} diff --git a/tests/exec_conformance.rs b/tests/exec_conformance.rs deleted file mode 100644 index f71886e..0000000 --- a/tests/exec_conformance.rs +++ /dev/null @@ -1,662 +0,0 @@ -#![allow(clippy::unwrap_used, clippy::panic, missing_docs)] - -mod common; - -use postmaster::adapter::KeyNaming; - -use std::os::unix::fs::PermissionsExt; -use std::path::Path; -use std::process::Command; - -#[test] -fn helper_ciphertext_decrypts_with_test_key() { - let v = common::enc("hello $(rm -rf /) `x` \"q\" \nline2"); - let b64 = v.strip_prefix("encrypted:").unwrap(); - let ct = { - use base64::Engine; - base64::engine::general_purpose::STANDARD - .decode(b64) - .unwrap() - }; - let sk = hex::decode(common::TEST_SK_HEX).unwrap(); - let pt = ecies::decrypt(&sk, &ct).unwrap(); - assert_eq!(pt, b"hello $(rm -rf /) `x` \"q\" \nline2"); -} - -#[test] -fn wrapped_base64_ciphertext_decrypts() { - // Test that decrypt_value tolerates ASCII whitespace in base64 payloads, - // matching dotenvx-rs's lenient decoding behavior. - let plaintext = "wrapped-value"; - let v = common::enc(plaintext); - let b64 = v.strip_prefix("encrypted:").unwrap(); - - // Wrap the base64 by inserting newlines every 20 chars - let mut wrapped = String::from("encrypted:"); - for (i, c) in b64.chars().enumerate() { - if i > 0 && i % 20 == 0 { - wrapped.push('\n'); - } - wrapped.push(c); - } - wrapped.push('\n'); - - // Create a temporary keys file with TEST_SK_HEX - let d = common::tmpdir("wrapped-base64"); - common::write_keys_file(&d, "", &[common::TEST_SK_HEX]); - let keys_path = d.join(".env.keys"); - - // Load the key ring - let ring = postmaster::keys::KeyRing::load(&keys_path, KeyNaming::Env).unwrap(); - - // Create a dummy env file path for error messages - let dummy_env = d.join(".env"); - - // decrypt_value should handle the wrapped (whitespace-containing) payload - let result = - postmaster::keys::decrypt_value(&dummy_env, "TEST_VAR", &wrapped, &ring, KeyNaming::Env); - - assert!(result.is_ok(), "wrapped base64 should decrypt successfully"); - let decrypted = result.unwrap(); - assert_eq!(decrypted.as_slice(), plaintext.as_bytes()); -} - -fn run_exec(config: &Path, sh: &str, envs: &[(&str, &str)]) -> std::process::Output { - let mut c = Command::new(env!("CARGO_BIN_EXE_postmaster")); - c.args(["exec", "--config"]) - .arg(config) - .args(["--", "/bin/sh", "-c", sh]) - // Hermeticity: an ambient SECRET/PLAIN/A in the test runner's own - // environment would flip the precedence-test outcomes below, since - // these are exactly the value-variable names the suite asserts on. - .env_remove("SECRET") - .env_remove("PLAIN") - .env_remove("A"); - for (k, v) in envs { - c.env(k, v); - } - c.output().unwrap() -} - -fn write_config(dir: &Path, json: &str) -> std::path::PathBuf { - let p = dir.join("exec.json"); - std::fs::write(&p, json).unwrap(); - p -} - -#[test] -fn env_mode_injects_decrypted_metacharacter_values_inert() { - let d = common::tmpdir("envmode"); - let val = "p@ss;|&`$(boom)\"'\nline2"; - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), - format!("SECRET=\"{}\"", common::enc(val)), - "PLAIN=just-plain".to_string(), - ], - ); - let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, - keys.display(), - env.display() - ), - ); - let sh = format!( - "printf %s \"$SECRET\" > '{d}'/secret.out && printf %s \"$PLAIN\" > '{d}'/plain.out && [ -z \"${{DOTENV_PUBLIC_KEY_PRODUCTION:-}}\" ]", - d = d.display() - ); - let out = run_exec(&cfg, &sh, &[]); - assert!( - out.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out.stderr) - ); - assert_eq!(std::fs::read(d.join("secret.out")).unwrap(), val.as_bytes()); - assert_eq!(std::fs::read(d.join("plain.out")).unwrap(), b"just-plain"); -} - -#[test] -fn env_mode_process_env_wins_without_overload() { - let d = common::tmpdir("envwins"); - let val = "decrypted-value"; - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), - format!("SECRET=\"{}\"", common::enc(val)), - ], - ); - let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); - - let cfg_no_overload = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"overload":false}}"#, - keys.display(), - env.display() - ), - ); - let sh1 = format!("printf %s \"$SECRET\" > '{d}'/out1", d = d.display()); - let out1 = run_exec(&cfg_no_overload, &sh1, &[("SECRET", "preset")]); - assert!( - out1.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out1.stderr) - ); - assert_eq!(std::fs::read(d.join("out1")).unwrap(), b"preset"); - - let cfg_overload = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"overload":true}}"#, - keys.display(), - env.display() - ), - ); - let sh2 = format!("printf %s \"$SECRET\" > '{d}'/out2", d = d.display()); - let out2 = run_exec(&cfg_overload, &sh2, &[("SECRET", "preset")]); - assert!( - out2.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out2.stderr) - ); - assert_eq!(std::fs::read(d.join("out2")).unwrap(), val.as_bytes()); -} - -#[test] -fn rotation_second_key_decrypts() { - let d = common::tmpdir("rotation"); - let val = "rotated-secret"; - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), - format!("SECRET=\"{}\"", common::enc(val)), - ], - ); - let bogus = "22".repeat(32); - let keys = common::write_keys_file(&d, "PRODUCTION", &[&bogus, common::TEST_SK_HEX]); - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, - keys.display(), - env.display() - ), - ); - let sh = format!("printf %s \"$SECRET\" > '{d}'/out", d = d.display()); - let out = run_exec(&cfg, &sh, &[]); - assert!( - out.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out.stderr) - ); - assert_eq!(std::fs::read(d.join("out")).unwrap(), val.as_bytes()); -} - -#[test] -fn strict_failure_refuses_exec() { - let d = common::tmpdir("strictfail"); - // Encrypt with a DIFFERENT key than the one in our keyring, so - // decryption must fail even though the ciphertext is well-formed. - let other_sk_hex = "22".repeat(32); - let other_sk_bytes = hex::decode(&other_sk_hex).unwrap(); - let other_sk = ecies::SecretKey::parse_slice(&other_sk_bytes).unwrap(); - let other_pk = ecies::PublicKey::from_secret_key(&other_sk); - let ct = ecies::encrypt(&other_pk.serialize_compressed(), b"unreachable").unwrap(); - let b64 = { - use base64::Engine; - base64::engine::general_purpose::STANDARD.encode(ct) - }; - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!( - "DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", - hex::encode(other_pk.serialize_compressed()) - ), - format!("SECRET=\"encrypted:{b64}\""), - ], - ); - let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"strict":true}}"#, - keys.display(), - env.display() - ), - ); - let sh = format!("printf %s \"$SECRET\" > '{d}'/out", d = d.display()); - let out = run_exec(&cfg, &sh, &[]); - assert!(!out.status.success()); - let stderr = String::from_utf8_lossy(&out.stderr); - assert!(stderr.contains("no key under"), "stderr: {stderr}"); - assert!(!d.join("out").exists()); -} - -#[test] -fn files_mode_writes_0600_pointers_and_passthrough() { - let d = common::tmpdir("filesmode"); - let secrets_dir = d.join("secrets"); - std::fs::create_dir_all(&secrets_dir).unwrap(); - let val = "file-secret"; - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), - format!("SECRET=\"{}\"", common::enc(val)), - "PLAIN=passthrough-val".to_string(), - ], - ); - let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"files","keys":[{{"file":"{}"}}],"env_files":["{}"],"secrets_dir":"{}","passthrough":["PLAIN"]}}"#, - keys.display(), - env.display(), - secrets_dir.display() - ), - ); - let sh = format!( - r#"printf %s "$SECRET_FILE" > '{d}'/secret_file.out && \ - cat "$SECRET_FILE" > '{d}'/secret_contents.out && \ - printf %s "${{SECRET:-UNSET}}" > '{d}'/secret_var.out && \ - printf %s "$PLAIN" > '{d}'/plain.out && \ - printf %s "${{POSTMASTER_SECRETS_DIR:-UNSET}}" > '{d}'/secretsdir.out"#, - d = d.display() - ); - let out = run_exec(&cfg, &sh, &[]); - assert!( - out.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out.stderr) - ); - assert_eq!( - std::fs::read_to_string(d.join("secret_file.out")).unwrap(), - secrets_dir.join("SECRET").display().to_string() - ); - assert_eq!( - std::fs::read(d.join("secret_contents.out")).unwrap(), - val.as_bytes() - ); - assert_eq!(std::fs::read(d.join("secret_var.out")).unwrap(), b"UNSET"); - assert_eq!( - std::fs::read(d.join("plain.out")).unwrap(), - b"passthrough-val" - ); - assert_eq!( - std::fs::read_to_string(d.join("secretsdir.out")).unwrap(), - "UNSET" - ); - - let md = std::fs::metadata(secrets_dir.join("SECRET")).unwrap(); - assert_eq!(md.permissions().mode() & 0o777, 0o600); -} - -#[test] -fn credentials_mode_systemd_pointers() { - let d = common::tmpdir("credsystemd"); - let creds_dir = d.join("creds"); - std::fs::create_dir_all(&creds_dir).unwrap(); - std::fs::write(creds_dir.join("DB_URL"), "abc").unwrap(); - let cfg = write_config(&d, r#"{"mode":"credentials","credential_keys":["DB_URL"]}"#); - let sh = format!( - "printf %s \"$DB_URL_FILE\" > '{d}'/dbfile.out && cat \"$DB_URL_FILE\" > '{d}'/dbcontents.out", - d = d.display() - ); - let out = run_exec( - &cfg, - &sh, - &[("CREDENTIALS_DIRECTORY", creds_dir.to_str().unwrap())], - ); - assert!( - out.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out.stderr) - ); - assert_eq!( - std::fs::read_to_string(d.join("dbfile.out")).unwrap(), - creds_dir.join("DB_URL").display().to_string() - ); - assert_eq!(std::fs::read(d.join("dbcontents.out")).unwrap(), b"abc"); - - // Without CREDENTIALS_DIRECTORY, the systemd path has nothing to point - // at: fail closed. Explicitly remove from child to ensure hermeticity. - let mut c = Command::new(env!("CARGO_BIN_EXE_postmaster")); - c.args(["exec", "--config"]) - .arg(&cfg) - .args(["--", "/bin/sh", "-c", "true"]) - .env_remove("CREDENTIALS_DIRECTORY"); - let out2 = c.output().unwrap(); - assert!(!out2.status.success()); -} - -#[test] -fn credentials_mode_fetch_loop() { - let d = common::tmpdir("credfetch"); - let secrets_dir = d.join("secrets"); - std::fs::create_dir_all(&secrets_dir).unwrap(); - let sock = d.join("k.sock"); - let listener = std::os::unix::net::UnixListener::bind(&sock).unwrap(); - let server = std::thread::spawn(move || { - if let Ok((mut s, _)) = listener.accept() { - use std::io::Write; - let _ = s.write_all(b"s3cret"); - let _ = s.shutdown(std::net::Shutdown::Both); - } - }); - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"credentials","credential_keys":["K"],"sockets":{{"K":"{}"}},"secrets_dir":"{}"}}"#, - sock.display(), - secrets_dir.display() - ), - ); - let sh = format!( - "printf %s \"$CREDENTIALS_DIRECTORY\" > '{d}'/creddir.out && cat '{sd}'/K > '{d}'/kcontents.out", - d = d.display(), - sd = secrets_dir.display() - ); - let out = run_exec(&cfg, &sh, &[]); - server.join().unwrap(); - assert!( - out.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out.stderr) - ); - assert_eq!( - std::fs::read_to_string(d.join("creddir.out")).unwrap(), - secrets_dir.display().to_string() - ); - assert_eq!(std::fs::read(d.join("kcontents.out")).unwrap(), b"s3cret"); - let md = std::fs::metadata(secrets_dir.join("K")).unwrap(); - assert_eq!(md.permissions().mode() & 0o777, 0o600); -} - -#[test] -fn multi_file_first_wins_and_overload_reverses() { - let d = common::tmpdir("multifile"); - let f1 = common::write_env_file(&d, ".env", &["A=first-file".to_string()]); - let f2 = common::write_env_file(&d, ".env.local", &["A=second-file".to_string()]); - let keys = common::write_keys_file(&d, "", &[common::TEST_SK_HEX]); - - let cfg_first = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}","{}"],"overload":false}}"#, - keys.display(), - f1.display(), - f2.display() - ), - ); - let sh1 = format!("printf %s \"$A\" > '{d}'/out1", d = d.display()); - let out1 = run_exec(&cfg_first, &sh1, &[]); - assert!( - out1.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out1.stderr) - ); - assert_eq!(std::fs::read(d.join("out1")).unwrap(), b"first-file"); - - let cfg_overload = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}","{}"],"overload":true}}"#, - keys.display(), - f1.display(), - f2.display() - ), - ); - let sh2 = format!("printf %s \"$A\" > '{d}'/out2", d = d.display()); - let out2 = run_exec(&cfg_overload, &sh2, &[]); - assert!( - out2.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out2.stderr) - ); - assert_eq!(std::fs::read(d.join("out2")).unwrap(), b"second-file"); -} - -#[test] -fn same_file_last_assignment_wins() { - let d = common::tmpdir("samelastwin"); - let first_val = "first-value"; - let second_val = "second-value"; - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), - format!("SECRET=\"{}\"", common::enc(first_val)), - format!("SECRET=\"{}\"", common::enc(second_val)), - ], - ); - let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, - keys.display(), - env.display() - ), - ); - let sh = format!("printf %s \"$SECRET\" > '{d}'/secret.out", d = d.display()); - let out = run_exec(&cfg, &sh, &[]); - assert!( - out.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out.stderr) - ); - assert_eq!( - std::fs::read(d.join("secret.out")).unwrap(), - second_val.as_bytes() - ); -} - -#[test] -fn nul_in_env_value_fails_closed() { - let d = common::tmpdir("nulval"); - let val = "before\0after"; - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), - format!("SECRET=\"{}\"", common::enc(val)), - ], - ); - let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); - - // env mode: fails closed with a message about NUL. - let cfg_env = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, - keys.display(), - env.display() - ), - ); - let out = run_exec(&cfg_env, "true", &[]); - assert!(!out.status.success()); - let stderr = String::from_utf8_lossy(&out.stderr); - assert!(stderr.contains("NUL"), "stderr: {stderr}"); - - // files mode: the exact bytes (including the NUL) reach the file. - let secrets_dir = d.join("secrets"); - std::fs::create_dir_all(&secrets_dir).unwrap(); - let cfg_files = write_config( - &d, - &format!( - r#"{{"mode":"files","keys":[{{"file":"{}"}}],"env_files":["{}"],"secrets_dir":"{}"}}"#, - keys.display(), - env.display(), - secrets_dir.display() - ), - ); - let sh = format!( - "cat '{sd}'/SECRET > '{d}'/out", - sd = secrets_dir.display(), - d = d.display() - ); - let out2 = run_exec(&cfg_files, &sh, &[]); - assert!( - out2.status.success(), - "stderr: {}", - String::from_utf8_lossy(&out2.stderr) - ); - assert_eq!(std::fs::read(d.join("out")).unwrap(), val.as_bytes()); -} - -#[test] -fn strict_false_skips_undecryptable_and_continues() { - let d = common::tmpdir("laxskip"); - // GOOD decrypts with TEST_SK_HEX; BAD uses a different key so it fails. - let other_sk_hex = "33".repeat(32); - let other_sk_bytes = hex::decode(&other_sk_hex).unwrap(); - let other_sk = ecies::SecretKey::parse_slice(&other_sk_bytes).unwrap(); - let other_pk = ecies::PublicKey::from_secret_key(&other_sk); - let bad_ct = ecies::encrypt(&other_pk.serialize_compressed(), b"unreachable").unwrap(); - let bad_b64 = { - use base64::Engine; - base64::engine::general_purpose::STANDARD.encode(bad_ct) - }; - - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), - format!("GOOD=\"{}\"", common::enc("lax-ok")), - format!("BAD=\"encrypted:{bad_b64}\""), - ], - ); - let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); - // strict:false: BAD should be skipped (logged), GOOD should still reach the child. - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"strict":false}}"#, - keys.display(), - env.display() - ), - ); - let sh = format!( - "printf %s \"${{GOOD:-UNSET}}\" > '{d}'/good.out && printf %s \"${{BAD:-UNSET}}\" > '{d}'/bad.out", - d = d.display() - ); - let out = run_exec(&cfg, &sh, &[]); - assert!( - out.status.success(), - "strict:false should continue past undecryptable value and launch the child\nstderr: {}", - String::from_utf8_lossy(&out.stderr) - ); - assert_eq!(std::fs::read(d.join("good.out")).unwrap(), b"lax-ok"); - // BAD was skipped: the child sees no BAD env var. - assert_eq!(std::fs::read(d.join("bad.out")).unwrap(), b"UNSET"); - // The stderr should mention the skip. - let stderr = String::from_utf8_lossy(&out.stderr); - assert!( - stderr.contains("non-strict: skipping BAD"), - "expected skip log in stderr, got: {stderr}" - ); -} - -#[test] -fn exec_rejects_non_identifier_key_at_exec_boundary() { - let d = common::tmpdir("badkey"); - // A dotted key like BAD.KEY parses fine as dotenv but is_ident rejects it. - let env = common::write_env_file(&d, ".env", &["BAD.KEY=oops".to_string()]); - let keys = common::write_keys_file(&d, "", &[common::TEST_SK_HEX]); - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, - keys.display(), - env.display() - ), - ); - let out = run_exec(&cfg, "true", &[]); - assert!(!out.status.success()); - let stderr = String::from_utf8_lossy(&out.stderr); - assert!( - stderr.contains("non-identifier"), - "expected 'non-identifier' in stderr, got: {stderr}" - ); -} - -#[test] -fn verify_keys_aborts_on_stale_keys_with_strict_false() { - // Audit finding #4: --verify-keys should catch stale keys even when - // strict is false. Encrypt with a different key than the one in the - // keyring, set strict:false, and pass --verify-keys. The exec must - // abort with a --verify-keys error rather than launching the child - // with no secrets. - let d = common::tmpdir("verifykeys"); - let other_sk_hex = "33".repeat(32); - let other_sk_bytes = hex::decode(&other_sk_hex).unwrap(); - let other_sk = ecies::SecretKey::parse_slice(&other_sk_bytes).unwrap(); - let other_pk = ecies::PublicKey::from_secret_key(&other_sk); - let ct = ecies::encrypt(&other_pk.serialize_compressed(), b"stale-secret").unwrap(); - let b64 = { - use base64::Engine; - base64::engine::general_purpose::STANDARD.encode(ct) - }; - let env = common::write_env_file( - &d, - ".env.production", - &[ - format!( - "DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", - hex::encode(other_pk.serialize_compressed()) - ), - format!("SECRET=\"encrypted:{b64}\""), - ], - ); - // Keyring has the TEST_SK_HEX key, NOT the other key — keys are stale. - let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); - let cfg = write_config( - &d, - &format!( - r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"strict":false}}"#, - keys.display(), - env.display() - ), - ); - // Without --verify-keys, strict:false would silently skip and succeed. - let sh = "true".to_string(); - let out_no_verify = run_exec(&cfg, &sh, &[]); - assert!( - out_no_verify.status.success(), - "without --verify-keys, strict:false should silently skip: {}", - String::from_utf8_lossy(&out_no_verify.stderr) - ); - - // With --verify-keys, the stale keys must be caught. - let mut c = Command::new(env!("CARGO_BIN_EXE_postmaster")); - c.args(["exec", "--config"]) - .arg(&cfg) - .args(["--verify-keys", "--", "true"]) - .env_remove("SECRET"); - let out = c.output().unwrap(); - assert!( - !out.status.success(), - "--verify-keys should abort on stale keys" - ); - let stderr = String::from_utf8_lossy(&out.stderr); - assert!( - stderr.contains("--verify-keys failed"), - "expected '--verify-keys failed' in stderr, got: {stderr}" - ); -} diff --git a/tests/exec_conformance/bundle.rs b/tests/exec_conformance/bundle.rs new file mode 100644 index 0000000..2df2191 --- /dev/null +++ b/tests/exec_conformance/bundle.rs @@ -0,0 +1,415 @@ +//! Bundle conformance tests. +//! +//! End-to-end bundle exec coverage: the actual binary, a real bundle +//! file, and key material loaded through `load_ring` — the seam where +//! the bundle-ring gap lived (unit tests build rings directly and never +//! saw it). + +use base64::Engine; +use base64::engine::general_purpose::STANDARD as BASE64; + +use crate::common; +use crate::{run_exec, write_config}; + +/// Encrypt `value` for the shared test key with AAD = the entry name, +/// exactly as the bundle adapter's suite requires. +fn enc_entry(name: &str, value: &str) -> String { + let pk = hex::decode(common::test_pk_hex()).unwrap(); + let ct = common::aad_fixture::encrypt(&pk, value.as_bytes(), name.as_bytes()); + BASE64.encode(ct) +} + +/// Write a v1 bundle file with the given (name, value) utf8 entries. +fn write_bundle(dir: &std::path::Path, entries: &[(&str, &str)]) -> std::path::PathBuf { + let entries: serde_json::Map = entries + .iter() + .map(|(name, value)| { + ( + name.to_string(), + serde_json::json!({ + "encoding": "utf8", + "ciphertext": enc_entry(name, value), + }), + ) + }) + .collect(); + let bundle = serde_json::json!({ + "format": "postmaster.bundle", + "version": 1, + "profile": "conformance", + "suite": "ecies-secp256k1-hkdf-sha256-aes-256-gcm-entry-aad", + "recipients": [{ "id": "test", "public_key": common::test_pk_hex() }], + "entries": entries, + }); + let p = dir.join("secrets.bundle.json"); + std::fs::write(&p, serde_json::to_vec_pretty(&bundle).unwrap()).unwrap(); + p +} + +/// A keys file carrying `POSTMASTER_KEY` (and optionally +/// `DOTENV_PRIVATE_KEY`), with the permissions `KeyRing::load` enforces. +fn write_keys(dir: &std::path::Path, with_dotenv: bool) -> std::path::PathBuf { + use std::os::unix::fs::PermissionsExt; + let mut content = format!("POSTMASTER_KEY=\"{}\"\n", common::TEST_SK_HEX); + if with_dotenv { + content.push_str(&format!("DOTENV_PRIVATE_KEY=\"{}\"\n", common::TEST_SK_HEX)); + } + let p = dir.join(".env.keys"); + std::fs::write(&p, content).unwrap(); + std::fs::set_permissions(&p, std::fs::Permissions::from_mode(0o600)).unwrap(); + p +} + +#[test] +fn bundle_exec_loads_postmaster_key_through_load_ring() { + // The real launcher must load POSTMASTER_KEY for bundle inputs. + let d = common::tmpdir("bundlee2e"); + let bundle = write_bundle(&d, &[("SECRET", "bundle-secret-value")]); + let keys = write_keys(&d, false); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"bundle_files":["{}"]}}"#, + keys.display(), + bundle.display() + ), + ); + let sh = format!("printf %s \"$SECRET\" > '{d}'/secret.out", d = d.display()); + let out = run_exec(&cfg, &sh, &[]); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!( + std::fs::read(d.join("secret.out")).unwrap(), + b"bundle-secret-value" + ); +} + +#[test] +fn exec_private_key_variables_are_not_inherited() { + let d = common::tmpdir("private-key-env"); + let env = common::write_env_file( + &d, + ".env", + &[ + format!("PLAIN=\"{}\"", common::enc("from-env")), + format!( + "POSTMASTER_KEY_STAGING=\"{}\"", + common::enc("reserved-output") + ), + ], + ); + let bundle = write_bundle(&d, &[("SECRET", "from-bundle")]); + let keys = write_keys(&d, true); + for (mode, file_source) in [ + ("env", false), + ("env", true), + ("files", false), + ("files", true), + ("credentials", false), + ] { + let secrets = d.join(format!("{mode}-{file_source}")); + std::fs::create_dir(&secrets).unwrap(); + let mut config = serde_json::json!({"mode": mode}); + if mode == "credentials" { + std::fs::write(secrets.join("SECRET"), "from-bundle").unwrap(); + config["credential_keys"] = serde_json::json!(["SECRET"]); + } else { + config["keys"] = if file_source { + serde_json::json!([{"file": keys}]) + } else { + serde_json::json!(["environment"]) + }; + config["env_files"] = serde_json::json!([env]); + config["bundle_files"] = serde_json::json!([bundle]); + config["overload"] = serde_json::json!(true); + if mode == "files" { + config["secrets_dir"] = serde_json::json!(secrets); + } + } + let cfg = write_config(&d, &config.to_string()); + let sh = r#" + [ "${DOTENV_PRIVATE_KEY+x}${DOTENV_PRIVATE_KEY_PRODUCTION+x}${POSTMASTER_KEY+x}${POSTMASTER_KEY_PRODUCTION+x}${POSTMASTER_KEY_STAGING+x}${POSTMASTER_KEY_STAGING_FILE+x}" = "" ] || { + echo 'private key variable reached the application' >&2; exit 42; + } + [ "$DOTENV_PRIVATE_KEYFOO" = keep-dotenv ] && + [ "$POSTMASTER_KEYFOO" = keep-bundle ] && + [ "$HOME" = /postmaster-test-home ] && [ "$PATH" = /usr/bin:/bin ] || exit 43 + if [ -n "${SECRET_FILE:-}" ]; then + [ "$(cat "$SECRET_FILE")" = from-bundle ] || exit 44 + if [ -n "${PLAIN_FILE:-}" ]; then + [ "$(cat "$PLAIN_FILE")" = from-env ] || exit 45 + fi + else + [ "$SECRET" = from-bundle ] && [ "$PLAIN" = from-env ] || exit 46 + fi + "#; + let out = run_exec( + &cfg, + sh, + &[ + ("DOTENV_PRIVATE_KEY", common::TEST_SK_HEX), + ("DOTENV_PRIVATE_KEY_PRODUCTION", common::TEST_SK_HEX), + ("POSTMASTER_KEY", common::TEST_SK_HEX), + ("POSTMASTER_KEY_PRODUCTION", common::TEST_SK_HEX), + ("DOTENV_PRIVATE_KEYFOO", "keep-dotenv"), + ("POSTMASTER_KEYFOO", "keep-bundle"), + ("HOME", "/postmaster-test-home"), + ("PATH", "/usr/bin:/bin"), + ("CREDENTIALS_DIRECTORY", secrets.to_str().unwrap()), + ], + ); + assert!( + out.status.success(), + "mode:{mode}, file_source:{file_source}, stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + } +} + +#[test] +fn bundle_private_key_entry_names_fail_before_launch() { + let d = common::tmpdir("reserved-bundle-keys"); + let keys = write_keys(&d, false); + for name in [ + "DOTENV_PRIVATE_KEY", + "DOTENV_PRIVATE_KEY_PRODUCTION", + "POSTMASTER_KEY", + "POSTMASTER_KEY_PRODUCTION", + ] { + let bundle = write_bundle(&d, &[(name, "reserved-output")]); + let cfg = write_config( + &d, + &serde_json::json!({ + "mode": "env", + "keys": [{"file": keys}], + "bundle_files": [bundle], + "strict": false, + "overload": true, + }) + .to_string(), + ); + let marker = d.join("started"); + let out = run_exec(&cfg, &format!("echo started > '{}'", marker.display()), &[]); + assert!(!out.status.success(), "reserved entry {name} was accepted"); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains(name) && stderr.contains("reserved"), + "{stderr}" + ); + assert!( + !marker.exists(), + "reserved entry {name} started the command" + ); + } +} + +#[test] +fn mixed_env_and_bundle_exec_resolves_both_adapters() { + // A config with both env_files and bundle_files requires BOTH + // namings in one ring (the adapter-aware load_ring signature's + // multi-naming path). + let d = common::tmpdir("bundle-mixed"); + let val = "p@ss;|&`$(boom)\"'\nline2"; + let env = common::write_env_file(&d, ".env", &[format!("PLAIN=\"{}\"", common::enc(val))]); + let bundle = write_bundle(&d, &[("SECRET", "from-bundle")]); + let keys = write_keys(&d, true); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"bundle_files":["{}"]}}"#, + keys.display(), + env.display(), + bundle.display() + ), + ); + let sh = format!( + "printf %s \"$SECRET\" > '{d}'/secret.out && printf %s \"$PLAIN\" > '{d}'/plain.out", + d = d.display() + ); + let out = run_exec(&cfg, &sh, &[]); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!(std::fs::read(d.join("secret.out")).unwrap(), b"from-bundle"); + assert_eq!(std::fs::read(d.join("plain.out")).unwrap(), val.as_bytes()); +} + +#[test] +fn bundle_exec_refuses_symlinked_bundle_file() { + // The O_NOFOLLOW open on bundle ciphertext must hold end-to-end — a planted symlink + // at a configured bundle path is a hard error, never a read-through. + let d = common::tmpdir("bundle-symlink"); + let bundle = write_bundle(&d, &[("SECRET", "unreachable")]); + let keys = write_keys(&d, false); + let link = d.join("linked.bundle.json"); + std::os::unix::fs::symlink(&bundle, &link).unwrap(); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"bundle_files":["{}"]}}"#, + keys.display(), + link.display() + ), + ); + let out = run_exec(&cfg, "true", &[]); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!(stderr.contains("symlink"), "stderr: {stderr}"); +} + +#[test] +fn bundle_env_precedence_matches_env_adapter() { + // Bundle values follow dotenv precedence: the process environment wins + // unless overload is enabled. + let d = common::tmpdir("bundle-prec"); + let bundle = write_bundle(&d, &[("SECRET", "from-bundle")]); + let keys = write_keys(&d, false); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"bundle_files":["{}"],"overload":false}}"#, + keys.display(), + bundle.display() + ), + ); + let sh = format!("printf %s \"$SECRET\" > '{d}'/out1", d = d.display()); + let out = run_exec(&cfg, &sh, &[("SECRET", "preset")]); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!(std::fs::read(d.join("out1")).unwrap(), b"preset"); + + let cfg_overload = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"bundle_files":["{}"],"overload":true}}"#, + keys.display(), + bundle.display() + ), + ); + let sh2 = format!("printf %s \"$SECRET\" > '{d}'/out2", d = d.display()); + let out2 = run_exec(&cfg_overload, &sh2, &[("SECRET", "preset")]); + assert!( + out2.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out2.stderr) + ); + assert_eq!(std::fs::read(d.join("out2")).unwrap(), b"from-bundle"); +} + +#[test] +fn bundle_files_follow_first_or_last_wins_precedence() { + let d = common::tmpdir("bundle-file-precedence"); + let first_dir = d.join("first"); + let last_dir = d.join("last"); + std::fs::create_dir(&first_dir).unwrap(); + std::fs::create_dir(&last_dir).unwrap(); + let first = write_bundle(&first_dir, &[("SECRET", "first-bundle"), ("FIRST", "one")]); + let last = write_bundle(&last_dir, &[("SECRET", "last-bundle"), ("LAST", "two")]); + let env = common::write_env_file(&d, ".env", &[format!("SECRET={}", common::enc("from-env"))]); + let keys = write_keys(&d, true); + for mode in ["env", "files"] { + for include_env in [false, true] { + for overload in [false, true] { + let mut config = serde_json::json!({ + "mode": mode, + "keys": [{"file": keys}], + "bundle_files": [first, last], + "overload": overload, + }); + if include_env { + config["env_files"] = serde_json::json!([env]); + } + if mode == "files" { + let dir = d.join(format!("files-{include_env}-{overload}")); + std::fs::create_dir(&dir).unwrap(); + config["secrets_dir"] = serde_json::json!(dir); + } + let cfg = write_config(&d, &config.to_string()); + let sh = if mode == "files" { + "cat \"$SECRET_FILE\"; printf '|'; cat \"$FIRST_FILE\"; printf '|'; cat \"$LAST_FILE\"" + } else { + "printf '%s|%s|%s' \"$SECRET\" \"$FIRST\" \"$LAST\"" + }; + let out = run_exec(&cfg, sh, &[]); + assert!( + out.status.success(), + "{}", + String::from_utf8_lossy(&out.stderr) + ); + let expected = if overload { + "last-bundle|one|two" + } else if include_env { + "from-env|one|two" + } else { + "first-bundle|one|two" + }; + assert_eq!( + out.stdout, + expected.as_bytes(), + "mode:{mode}, include_env:{include_env}, overload:{overload}" + ); + } + } + } +} + +#[test] +fn bundle_shadowed_nul_value_still_fails_closed() { + let d = common::tmpdir("bundle-shadowed-nul"); + let first_dir = d.join("first"); + std::fs::create_dir(&first_dir).unwrap(); + let first = write_bundle(&first_dir, &[("SECRET", "valid")]); + let last = write_bundle(&d, &[("SECRET", "invalid\0value")]); + let keys = write_keys(&d, false); + let cfg = write_config( + &d, + &serde_json::json!({ + "mode": "env", + "keys": [{"file": keys}], + "bundle_files": [first, last], + "strict": false, + }) + .to_string(), + ); + let out = run_exec(&cfg, "true", &[]); + assert!(!out.status.success()); + assert!(String::from_utf8_lossy(&out.stderr).contains("NUL byte")); +} + +#[test] +fn bundle_nul_value_is_a_hard_error_under_any_strictness() { + // An env-bound bundle value containing NUL is a HARD error — one rule for every + // env-bound value. strict:false must NOT skip it the way it skips undecryptable + // values. + let d = common::tmpdir("bundle-nul"); + let bundle = write_bundle(&d, &[("SECRET", "before\0after")]); + let keys = write_keys(&d, false); + for strict in [true, false] { + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"bundle_files":["{}"],"strict":{strict}}}"#, + keys.display(), + bundle.display() + ), + ); + let out = run_exec(&cfg, "true", &[]); + assert!( + !out.status.success(), + "strict:{strict} must still fail closed on a NUL value" + ); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("NUL byte"), + "strict:{strict} stderr: {stderr}" + ); + } +} diff --git a/tests/exec_conformance/daemon.rs b/tests/exec_conformance/daemon.rs new file mode 100644 index 0000000..1c2b484 --- /dev/null +++ b/tests/exec_conformance/daemon.rs @@ -0,0 +1,201 @@ +//! Daemon end-to-end conformance: the real binary in serve mode, a real bound socket, +//! and the real fetch client — the serve/fetch roundtrip and the startup preflight +//! refusal, which the unit tests only exercise in-process. + +use sha2::Digest as _; +use std::process::Command; +use std::time::{Duration, Instant}; + +use crate::common; + +/// Kill the daemon on drop (panic paths included) so a failed assertion +/// can't leak a serving process. +struct KillOnDrop(Option); + +impl Drop for KillOnDrop { + fn drop(&mut self) { + if let Some(mut c) = self.0.take() { + let _ = c.kill(); + let _ = c.wait(); + } + } +} + +/// Wait for the daemon's socket to accept connections (the file existing +/// is not enough — a dead daemon leaves the socket file behind), bailing +/// early with the daemon's stderr if the process exits first. +fn wait_for_socket( + daemon: &mut std::process::Child, + sock: &std::path::Path, + timeout: Duration, +) -> Result<(), String> { + use std::io::Read as _; + let deadline = Instant::now() + timeout; + while Instant::now() < deadline { + // A successful connect means a live listener. The probe is itself + // served like a fetch (one serialized connection) and dropped. + if std::os::unix::net::UnixStream::connect(sock).is_ok() { + return Ok(()); + } + if let Some(status) = daemon.try_wait().map_err(|e| e.to_string())? { + let mut stderr = String::new(); + if let Some(mut h) = daemon.stderr.take() { + let _ = h.read_to_string(&mut stderr); + } + return Err(format!("daemon exited before binding ({status}): {stderr}")); + } + std::thread::sleep(Duration::from_millis(10)); + } + Err(format!( + "daemon did not accept on {} within {timeout:?}", + sock.display() + )) +} + +#[test] +fn daemon_serves_a_real_fetch_roundtrip() { + for mask in ["000", "022", "077"] { + daemon_roundtrip(mask, None); + } +} + +#[test] +fn daemon_serves_configured_peer_under_any_umask() { + let out = Command::new("id").arg("-un").output().unwrap(); + assert!(out.status.success()); + let user = String::from_utf8(out.stdout).unwrap(); + for mask in ["000", "022", "077"] { + daemon_roundtrip(mask, Some(user.trim())); + } +} + +fn daemon_roundtrip(mask: &str, peer_user: Option<&str>) { + let d = common::tmpdir("daemon"); + let encrypted = common::enc("postgres://real-roundtrip"); + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("DB_URL=\"{}\"", encrypted), + ], + ); + let hash = hex::encode(sha2::Sha256::digest(std::fs::read(&env).unwrap())); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + // Bound directly under the tmpdir: unix socket paths are length-capped + // (104 bytes on darwin), and the tmpdir path is already long. + let sock = d.join("DB_URL.sock"); + let cfg = d.join("daemon.json"); + std::fs::write( + &cfg, + serde_json::json!({ + "keys": {"file": keys}, + "credentials": {sock.to_str().unwrap(): { + "env_file": env, + "key": "DB_URL", + "peer_user": peer_user, + "env_file_sha256": [hash], + }}, + }) + .to_string(), + ) + .unwrap(); + + // The suite runs as the test user: --bind (no systemd activation + // here) and --allow-nonroot (the peer ACL's root-only default would + // refuse our own fetch when no peer_user is configured). + // The shell sets the child's mask without changing the test process. + let daemon = Command::new("/bin/sh") + .args([ + "-c", + "umask \"$1\"; shift; exec \"$@\"", + "postmaster-test", + mask, + env!("CARGO_BIN_EXE_postmaster"), + ]) + .args(["--config"]) + .arg(&cfg) + .args(["--bind", "--allow-nonroot"]) + .stderr(std::process::Stdio::piped()) + .spawn() + .unwrap(); + let mut guard = KillOnDrop(Some(daemon)); + wait_for_socket(guard.0.as_mut().unwrap(), &sock, Duration::from_secs(10)).unwrap(); + + // A configured peer needs write access; otherwise the socket is owner-only. + use std::os::unix::fs::PermissionsExt as _; + let mode = std::fs::metadata(&sock).unwrap().permissions().mode() & 0o777; + let expected = if peer_user.is_some() { 0o666 } else { 0o600 }; + assert_eq!(mode, expected, "socket mode under umask {mask}"); + + let out = Command::new(env!("CARGO_BIN_EXE_postmaster")) + .arg("fetch") + .arg(&sock) + .output() + .unwrap(); + assert!( + out.status.success(), + "fetch stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!(out.stdout, b"postgres://real-roundtrip"); + + let original = std::fs::read(&env).unwrap(); + for replacement in [ + format!("DB_URL='{}'\n", common::enc("foreign-secret")), + "DB_URL=${PATH}\n".into(), + ] { + std::fs::write(&env, replacement).unwrap(); + let refused = Command::new(env!("CARGO_BIN_EXE_postmaster")) + .arg("fetch") + .arg(&sock) + .output() + .unwrap(); + assert!(!refused.status.success()); + assert!(refused.stdout.is_empty()); + } + std::fs::write(&env, original).unwrap(); + let restored = Command::new(env!("CARGO_BIN_EXE_postmaster")) + .arg("fetch") + .arg(&sock) + .output() + .unwrap(); + assert!(restored.status.success()); + assert_eq!(restored.stdout, b"postgres://real-roundtrip"); +} + +#[test] +fn daemon_preflight_refuses_an_empty_credential_at_startup() { + // Zero bytes means refusal on the wire; reject empty values at startup + // and name the key rather than starting a daemon that cannot serve it. + let d = common::tmpdir("daemonpre"); + let env = common::write_env_file(&d, ".env", &["EMPTY=".to_string()]); + let keys = common::write_keys_file(&d, "", &[common::TEST_SK_HEX]); + let sock = d.join("EMPTY.sock"); + let cfg = d.join("daemon.json"); + std::fs::write( + &cfg, + format!( + r#"{{"keys":{{"file":"{}"}},"credentials":{{"{}":{{"env_file":"{}","key":"EMPTY","env_file_sha256":["7819c04858487b8325a083235e0697f271991cb446086084807fec586dc27427"]}}}}}}"#, + keys.display(), + sock.display(), + env.display() + ), + ) + .unwrap(); + + // Startup fails before any bind, so output() returns promptly. + let out = Command::new(env!("CARGO_BIN_EXE_postmaster")) + .args(["--config"]) + .arg(&cfg) + .args(["--bind", "--allow-nonroot"]) + .output() + .unwrap(); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!(stderr.contains("empty value"), "stderr: {stderr}"); + assert!( + !sock.exists(), + "a preflight refusal must happen before any socket is bound" + ); +} diff --git a/tests/exec_conformance/env_mode.rs b/tests/exec_conformance/env_mode.rs new file mode 100644 index 0000000..9172b29 --- /dev/null +++ b/tests/exec_conformance/env_mode.rs @@ -0,0 +1,244 @@ +use crate::common; +use crate::{run_exec, write_config}; + +#[test] +fn env_mode_injects_decrypted_metacharacter_values_inert() { + let d = common::tmpdir("envmode"); + let val = "p@ss;|&`$(boom)\"'\nline2"; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc(val)), + "PLAIN=just-plain".to_string(), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, + keys.display(), + env.display() + ), + ); + let sh = format!( + "printf %s \"$SECRET\" > '{d}'/secret.out && printf %s \"$PLAIN\" > '{d}'/plain.out && [ -z \"${{DOTENV_PUBLIC_KEY_PRODUCTION:-}}\" ]", + d = d.display() + ); + let out = run_exec(&cfg, &sh, &[]); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!(std::fs::read(d.join("secret.out")).unwrap(), val.as_bytes()); + assert_eq!(std::fs::read(d.join("plain.out")).unwrap(), b"just-plain"); +} + +#[test] +fn env_mode_process_env_wins_without_overload() { + let d = common::tmpdir("envwins"); + let val = "decrypted-value"; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc(val)), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + + let cfg_no_overload = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"overload":false}}"#, + keys.display(), + env.display() + ), + ); + let sh1 = format!("printf %s \"$SECRET\" > '{d}'/out1", d = d.display()); + let out1 = run_exec(&cfg_no_overload, &sh1, &[("SECRET", "preset")]); + assert!( + out1.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out1.stderr) + ); + assert_eq!(std::fs::read(d.join("out1")).unwrap(), b"preset"); + + let cfg_overload = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"overload":true}}"#, + keys.display(), + env.display() + ), + ); + let sh2 = format!("printf %s \"$SECRET\" > '{d}'/out2", d = d.display()); + let out2 = run_exec(&cfg_overload, &sh2, &[("SECRET", "preset")]); + assert!( + out2.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out2.stderr) + ); + assert_eq!(std::fs::read(d.join("out2")).unwrap(), val.as_bytes()); +} + +#[test] +fn multi_file_first_wins_and_overload_reverses() { + let d = common::tmpdir("multifile"); + let f1 = common::write_env_file(&d, ".env", &["A=first-file".to_string()]); + let f2 = common::write_env_file(&d, ".env.local", &["A=second-file".to_string()]); + let keys = common::write_keys_file(&d, "", &[common::TEST_SK_HEX]); + + let cfg_first = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}","{}"],"overload":false}}"#, + keys.display(), + f1.display(), + f2.display() + ), + ); + let sh1 = format!("printf %s \"$A\" > '{d}'/out1", d = d.display()); + let out1 = run_exec(&cfg_first, &sh1, &[]); + assert!( + out1.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out1.stderr) + ); + assert_eq!(std::fs::read(d.join("out1")).unwrap(), b"first-file"); + + let cfg_overload = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}","{}"],"overload":true}}"#, + keys.display(), + f1.display(), + f2.display() + ), + ); + let sh2 = format!("printf %s \"$A\" > '{d}'/out2", d = d.display()); + let out2 = run_exec(&cfg_overload, &sh2, &[]); + assert!( + out2.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out2.stderr) + ); + assert_eq!(std::fs::read(d.join("out2")).unwrap(), b"second-file"); +} + +#[test] +fn same_file_last_assignment_wins() { + let d = common::tmpdir("samelastwin"); + let first_val = "first-value"; + let second_val = "second-value"; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc(first_val)), + format!("SECRET=\"{}\"", common::enc(second_val)), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, + keys.display(), + env.display() + ), + ); + let sh = format!("printf %s \"$SECRET\" > '{d}'/secret.out", d = d.display()); + let out = run_exec(&cfg, &sh, &[]); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!( + std::fs::read(d.join("secret.out")).unwrap(), + second_val.as_bytes() + ); +} + +#[test] +fn nul_in_env_value_fails_closed() { + let d = common::tmpdir("nulval"); + let val = "before\0after"; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc(val)), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + + // env mode: fails closed with a message about NUL. + let cfg_env = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, + keys.display(), + env.display() + ), + ); + let out = run_exec(&cfg_env, "true", &[]); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!(stderr.contains("NUL"), "stderr: {stderr}"); + + // files mode: the exact bytes (including the NUL) reach the file. + let secrets_dir = d.join("secrets"); + std::fs::create_dir_all(&secrets_dir).unwrap(); + let cfg_files = write_config( + &d, + &format!( + r#"{{"mode":"files","keys":[{{"file":"{}"}}],"env_files":["{}"],"secrets_dir":"{}"}}"#, + keys.display(), + env.display(), + secrets_dir.display() + ), + ); + let sh = format!( + "cat '{sd}'/SECRET > '{d}'/out", + sd = secrets_dir.display(), + d = d.display() + ); + let out2 = run_exec(&cfg_files, &sh, &[]); + assert!( + out2.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out2.stderr) + ); + assert_eq!(std::fs::read(d.join("out")).unwrap(), val.as_bytes()); +} + +#[test] +fn exec_rejects_non_identifier_key_at_exec_boundary() { + let d = common::tmpdir("badkey"); + // A dotted key like BAD.KEY parses fine as dotenv but is_ident rejects it. + let env = common::write_env_file(&d, ".env", &["BAD.KEY=oops".to_string()]); + let keys = common::write_keys_file(&d, "", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, + keys.display(), + env.display() + ), + ); + let out = run_exec(&cfg, "true", &[]); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("non-identifier"), + "expected 'non-identifier' in stderr, got: {stderr}" + ); +} diff --git a/tests/exec_conformance/files_mode.rs b/tests/exec_conformance/files_mode.rs new file mode 100644 index 0000000..3810e10 --- /dev/null +++ b/tests/exec_conformance/files_mode.rs @@ -0,0 +1,285 @@ +use std::process::Command; + +use crate::common; +use crate::{run_exec, write_config}; + +#[test] +fn files_mode_writes_0600_pointers_and_passthrough() { + let d = common::tmpdir("filesmode"); + let secrets_dir = d.join("secrets"); + std::fs::create_dir_all(&secrets_dir).unwrap(); + let val = "file-secret"; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc(val)), + "PLAIN=passthrough-val".to_string(), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"files","keys":[{{"file":"{}"}}],"env_files":["{}"],"secrets_dir":"{}","passthrough":["PLAIN"]}}"#, + keys.display(), + env.display(), + secrets_dir.display() + ), + ); + let sh = format!( + r#"printf %s "$SECRET_FILE" > '{d}'/secret_file.out && \ + cat "$SECRET_FILE" > '{d}'/secret_contents.out && \ + printf %s "${{SECRET:-UNSET}}" > '{d}'/secret_var.out && \ + printf %s "$PLAIN" > '{d}'/plain.out && \ + printf %s "${{POSTMASTER_SECRETS_DIR:-UNSET}}" > '{d}'/secretsdir.out && \ + find "$SECRET_FILE" -perm 600 -print | grep -q ."#, + d = d.display() + ); + let out = run_exec(&cfg, &sh, &[]); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!( + std::fs::read_to_string(d.join("secret_file.out")).unwrap(), + secrets_dir.join("SECRET").display().to_string() + ); + assert_eq!( + std::fs::read(d.join("secret_contents.out")).unwrap(), + val.as_bytes() + ); + assert_eq!(std::fs::read(d.join("secret_var.out")).unwrap(), b"UNSET"); + assert_eq!( + std::fs::read(d.join("plain.out")).unwrap(), + b"passthrough-val" + ); + assert_eq!( + std::fs::read_to_string(d.join("secretsdir.out")).unwrap(), + "UNSET" + ); + + // The 0600 check ran inside the service above (the file must be + // exactly 0600 while it exists). Once the service exits, the sibling + // monitor removes the plaintext (cleanup on every death path) — + // run_exec returning implies the monitor has already exited: it + // inherits postmaster's stdout/stderr pipe ends across the fork and + // output() only sees EOF after the monitor's cleanup has run. + assert!( + !secrets_dir.join("SECRET").exists(), + "the sibling monitor must remove plaintext files on service death" + ); +} + +#[test] +fn credentials_mode_systemd_pointers() { + let d = common::tmpdir("credsystemd"); + let creds_dir = d.join("creds"); + std::fs::create_dir_all(&creds_dir).unwrap(); + std::fs::write(creds_dir.join("DB_URL"), "abc").unwrap(); + let cfg = write_config(&d, r#"{"mode":"credentials","credential_keys":["DB_URL"]}"#); + let sh = format!( + "printf %s \"$DB_URL_FILE\" > '{d}'/dbfile.out && cat \"$DB_URL_FILE\" > '{d}'/dbcontents.out", + d = d.display() + ); + let out = run_exec( + &cfg, + &sh, + &[("CREDENTIALS_DIRECTORY", creds_dir.to_str().unwrap())], + ); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!( + std::fs::read_to_string(d.join("dbfile.out")).unwrap(), + creds_dir.join("DB_URL").display().to_string() + ); + assert_eq!(std::fs::read(d.join("dbcontents.out")).unwrap(), b"abc"); + + // Without CREDENTIALS_DIRECTORY, the systemd path has nothing to point + // at: fail closed. Explicitly remove from child to ensure hermeticity. + let mut c = Command::new(env!("CARGO_BIN_EXE_postmaster")); + c.args(["exec", "--config"]) + .arg(&cfg) + .args(["--", "/bin/sh", "-c", "true"]) + .env_remove("CREDENTIALS_DIRECTORY"); + let out2 = c.output().unwrap(); + assert!(!out2.status.success()); +} + +#[test] +fn credentials_mode_fetch_loop() { + let d = common::tmpdir("credfetch"); + let secrets_dir = d.join("secrets"); + std::fs::create_dir_all(&secrets_dir).unwrap(); + let sock = d.join("k.sock"); + let listener = std::os::unix::net::UnixListener::bind(&sock).unwrap(); + let server = std::thread::spawn(move || { + if let Ok((mut s, _)) = listener.accept() { + use std::io::Write; + let _ = s.write_all(b"s3cret"); + let _ = s.shutdown(std::net::Shutdown::Both); + } + }); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"credentials","credential_keys":["K"],"sockets":{{"K":"{}"}},"secrets_dir":"{}"}}"#, + sock.display(), + secrets_dir.display() + ), + ); + let sh = format!( + "printf %s \"$CREDENTIALS_DIRECTORY\" > '{d}'/creddir.out && cat '{sd}'/K > '{d}'/kcontents.out && find '{sd}/K' -perm 600 -print | grep -q .", + d = d.display(), + sd = secrets_dir.display() + ); + let out = run_exec(&cfg, &sh, &[]); + if !out.status.success() { + // Hang guard: a regression that fails before connecting would leave the mock + // parked in accept() and the join below would hang the whole suite. Nudge the + // listener with a dummy connection so the thread can finish. + let _ = std::os::unix::net::UnixStream::connect(&sock); + } + server.join().unwrap(); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!( + std::fs::read_to_string(d.join("creddir.out")).unwrap(), + secrets_dir.display().to_string() + ); + assert_eq!(std::fs::read(d.join("kcontents.out")).unwrap(), b"s3cret"); + // The 0600 check ran inside the service above; after the service + // exits the sibling monitor removes the plaintext (see the files-mode + // test for why run_exec returning implies the monitor has exited). + assert!( + !secrets_dir.join("K").exists(), + "the sibling monitor must remove plaintext files on service death" + ); +} + +#[test] +fn files_mode_exec_failure_leaves_only_the_sentinel() { + // An execvp failure must unwind the plaintext writes — after a failed exec the + // secrets dir holds ONLY the managed sentinel, never secret files. + let d = common::tmpdir("files-execfail"); + let secrets_dir = d.join("secrets"); + std::fs::create_dir_all(&secrets_dir).unwrap(); + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc("exec-fail-secret")), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"files","keys":[{{"file":"{}"}}],"env_files":["{}"],"secrets_dir":"{}"}}"#, + keys.display(), + env.display(), + secrets_dir.display() + ), + ); + let mut c = Command::new(env!("CARGO_BIN_EXE_postmaster")); + c.args(["exec", "--config"]) + .arg(&cfg) + .args(["--", "/nonexistent-pm-binary"]) + .env_remove("SECRET"); + let out = c.output().unwrap(); + assert!(!out.status.success()); + + let leftovers: Vec = std::fs::read_dir(&secrets_dir) + .unwrap() + .map(|e| e.unwrap().file_name().to_string_lossy().into_owned()) + .collect(); + assert_eq!( + leftovers, + vec![postmaster::secret_files::MANAGED_SENTINEL.to_string()], + "only the managed sentinel may survive a failed exec" + ); +} + +#[test] +fn files_mode_passthrough_nul_fails_closed_with_cleanup() { + // A passthrough value containing NUL cannot become an env var — fail closed AND + // unwind the secret file that was already written for it. + let d = common::tmpdir("files-ptnul"); + let secrets_dir = d.join("secrets"); + std::fs::create_dir_all(&secrets_dir).unwrap(); + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc("before\0after")), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"files","keys":[{{"file":"{}"}}],"env_files":["{}"],"secrets_dir":"{}","passthrough":["SECRET"]}}"#, + keys.display(), + env.display(), + secrets_dir.display() + ), + ); + let out = run_exec(&cfg, "true", &[]); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("passthrough value contains NUL"), + "stderr: {stderr}" + ); + assert!( + !secrets_dir.join("SECRET").exists(), + "the written secret file must be unwound on the passthrough-NUL failure" + ); +} + +#[test] +fn files_mode_refuses_symlinked_secrets_dir() { + // A symlinked secrets_dir is a hard error before any plaintext is written — and the + // link target stays untouched. + let d = common::tmpdir("files-dirlink"); + let real = d.join("real-secrets"); + std::fs::create_dir_all(&real).unwrap(); + let link = d.join("linked-secrets"); + std::os::unix::fs::symlink(&real, &link).unwrap(); + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc("unreachable")), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"files","keys":[{{"file":"{}"}}],"env_files":["{}"],"secrets_dir":"{}"}}"#, + keys.display(), + env.display(), + link.display() + ), + ); + let out = run_exec(&cfg, "true", &[]); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!(stderr.contains("symlink"), "stderr: {stderr}"); + assert!( + std::fs::read_dir(&real).unwrap().next().is_none(), + "the symlink target must stay untouched" + ); +} diff --git a/tests/exec_conformance/keys_verify.rs b/tests/exec_conformance/keys_verify.rs new file mode 100644 index 0000000..b79fb81 --- /dev/null +++ b/tests/exec_conformance/keys_verify.rs @@ -0,0 +1,264 @@ +use std::process::Command; + +use crate::common; +use crate::{run_exec, write_config}; + +#[test] +fn rotation_second_key_decrypts() { + let d = common::tmpdir("rotation"); + let val = "rotated-secret"; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("SECRET=\"{}\"", common::enc(val)), + ], + ); + let bogus = "22".repeat(32); + let keys = common::write_keys_file(&d, "PRODUCTION", &[&bogus, common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"]}}"#, + keys.display(), + env.display() + ), + ); + let sh = format!("printf %s \"$SECRET\" > '{d}'/out", d = d.display()); + let out = run_exec(&cfg, &sh, &[]); + assert!( + out.status.success(), + "stderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!(std::fs::read(d.join("out")).unwrap(), val.as_bytes()); +} + +#[test] +fn strict_failure_refuses_exec() { + let d = common::tmpdir("strictfail"); + // Encrypt with a DIFFERENT key than the one in our keyring, so + // decryption must fail even though the ciphertext is well-formed. + let other_sk_hex = "22".repeat(32); + let other_sk_bytes = hex::decode(&other_sk_hex).unwrap(); + let other_sk = ecies::SecretKey::parse_slice(&other_sk_bytes).unwrap(); + let other_pk = ecies::PublicKey::from_secret_key(&other_sk); + let ct = ecies::encrypt(&other_pk.serialize_compressed(), b"unreachable").unwrap(); + let b64 = { + use base64::Engine; + base64::engine::general_purpose::STANDARD.encode(ct) + }; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!( + "DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", + hex::encode(other_pk.serialize_compressed()) + ), + format!("SECRET=\"encrypted:{b64}\""), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"strict":true}}"#, + keys.display(), + env.display() + ), + ); + let sh = format!("printf %s \"$SECRET\" > '{d}'/out", d = d.display()); + let out = run_exec(&cfg, &sh, &[]); + assert!(!out.status.success()); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!(stderr.contains("no key under"), "stderr: {stderr}"); + assert!(!d.join("out").exists()); +} + +#[test] +fn strict_false_skips_undecryptable_and_continues() { + let d = common::tmpdir("laxskip"); + // GOOD decrypts with TEST_SK_HEX; BAD uses a different key so it fails. + let other_sk_hex = "33".repeat(32); + let other_sk_bytes = hex::decode(&other_sk_hex).unwrap(); + let other_sk = ecies::SecretKey::parse_slice(&other_sk_bytes).unwrap(); + let other_pk = ecies::PublicKey::from_secret_key(&other_sk); + let bad_ct = ecies::encrypt(&other_pk.serialize_compressed(), b"unreachable").unwrap(); + let bad_b64 = { + use base64::Engine; + base64::engine::general_purpose::STANDARD.encode(bad_ct) + }; + + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + format!("GOOD=\"{}\"", common::enc("lax-ok")), + format!("BAD=\"encrypted:{bad_b64}\""), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + // strict:false: BAD should be skipped (logged), GOOD should still reach the child. + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"strict":false}}"#, + keys.display(), + env.display() + ), + ); + let sh = format!( + "printf %s \"${{GOOD:-UNSET}}\" > '{d}'/good.out && printf %s \"${{BAD:-UNSET}}\" > '{d}'/bad.out", + d = d.display() + ); + let out = run_exec(&cfg, &sh, &[]); + assert!( + out.status.success(), + "strict:false should continue past undecryptable value and launch the child\nstderr: {}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!(std::fs::read(d.join("good.out")).unwrap(), b"lax-ok"); + // BAD was skipped: the child sees no BAD env var. + assert_eq!(std::fs::read(d.join("bad.out")).unwrap(), b"UNSET"); + // The stderr should mention the skip. + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("non-strict: skipping BAD"), + "expected skip log in stderr, got: {stderr}" + ); +} + +#[test] +fn verify_keys_aborts_on_stale_keys_with_strict_false() { + // --verify-keys should catch stale keys even when strict is false. Encrypt with a + // different key than the one in the keyring, set strict:false, and pass + // --verify-keys. The exec must abort with a --verify-keys error rather than + // launching the child with no secrets. + let d = common::tmpdir("verifykeys"); + let other_sk_hex = "33".repeat(32); + let other_sk_bytes = hex::decode(&other_sk_hex).unwrap(); + let other_sk = ecies::SecretKey::parse_slice(&other_sk_bytes).unwrap(); + let other_pk = ecies::PublicKey::from_secret_key(&other_sk); + let ct = ecies::encrypt(&other_pk.serialize_compressed(), b"stale-secret").unwrap(); + let b64 = { + use base64::Engine; + base64::engine::general_purpose::STANDARD.encode(ct) + }; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!( + "DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", + hex::encode(other_pk.serialize_compressed()) + ), + format!("SECRET=\"encrypted:{b64}\""), + ], + ); + // Keyring has the TEST_SK_HEX key, NOT the other key — keys are stale. + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"strict":false}}"#, + keys.display(), + env.display() + ), + ); + // Without --verify-keys, strict:false would silently skip and succeed. + let sh = "true".to_string(); + let out_no_verify = run_exec(&cfg, &sh, &[]); + assert!( + out_no_verify.status.success(), + "without --verify-keys, strict:false should silently skip: {}", + String::from_utf8_lossy(&out_no_verify.stderr) + ); + + // With --verify-keys, the stale keys must be caught. + let mut c = Command::new(env!("CARGO_BIN_EXE_postmaster")); + c.args(["exec", "--config"]) + .arg(&cfg) + .args(["--verify-keys", "--", "true"]) + .env_remove("SECRET"); + let out = c.output().unwrap(); + assert!( + !out.status.success(), + "--verify-keys should abort on stale keys" + ); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("--verify-keys failed"), + "expected '--verify-keys failed' in stderr, got: {stderr}" + ); +} + +#[test] +fn verify_keys_aborts_on_partial_failure_with_strict_false() { + // --verify-keys must reject partial decryption even when strict:false would + // allow the remaining values to launch the child. + let d = common::tmpdir("verifykeys-partial"); + let other_sk_hex = "33".repeat(32); + let other_sk_bytes = hex::decode(&other_sk_hex).unwrap(); + let other_sk = ecies::SecretKey::parse_slice(&other_sk_bytes).unwrap(); + let other_pk = ecies::PublicKey::from_secret_key(&other_sk); + let stale_ct = ecies::encrypt(&other_pk.serialize_compressed(), b"stale-secret").unwrap(); + let stale_b64 = { + use base64::Engine; + base64::engine::general_purpose::STANDARD.encode(stale_ct) + }; + let env = common::write_env_file( + &d, + ".env.production", + &[ + format!("DOTENV_PUBLIC_KEY_PRODUCTION=\"{}\"", common::test_pk_hex()), + // Decrypts with the keyring's key — the resolved set is + // non-empty, so a count-only check would miss the failure. + format!("SECRET_GOOD=\"{}\"", common::enc("good-secret")), + // Encrypted to a key NOT in the keyring — skipped under + // strict:false. This is the partial-rotation case. + format!("SECRET_STALE=\"encrypted:{stale_b64}\""), + ], + ); + let keys = common::write_keys_file(&d, "PRODUCTION", &[common::TEST_SK_HEX]); + let cfg = write_config( + &d, + &format!( + r#"{{"mode":"env","keys":[{{"file":"{}"}}],"env_files":["{}"],"strict":false}}"#, + keys.display(), + env.display() + ), + ); + // Without --verify-keys the partial set launches silently: + // SECRET_GOOD is served, SECRET_STALE is dropped. + let out_no_verify = run_exec(&cfg, "test \"$SECRET_GOOD\" = good-secret", &[]); + assert!( + out_no_verify.status.success(), + "without --verify-keys, strict:false should silently serve the partial set: {}", + String::from_utf8_lossy(&out_no_verify.stderr) + ); + + // With --verify-keys, the recorded skip must abort the launch. + let mut c = Command::new(env!("CARGO_BIN_EXE_postmaster")); + c.args(["exec", "--config"]) + .arg(&cfg) + .args(["--verify-keys", "--", "true"]) + .env_remove("SECRET_GOOD") + .env_remove("SECRET_STALE"); + let out = c.output().unwrap(); + assert!( + !out.status.success(), + "--verify-keys should abort on a partial decryption failure" + ); + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + stderr.contains("--verify-keys failed"), + "expected '--verify-keys failed' in stderr, got: {stderr}" + ); + assert!( + stderr.contains("SECRET_STALE"), + "expected the skipped key name in stderr, got: {stderr}" + ); +} diff --git a/tests/exec_conformance/main.rs b/tests/exec_conformance/main.rs new file mode 100644 index 0000000..5032b6f --- /dev/null +++ b/tests/exec_conformance/main.rs @@ -0,0 +1,114 @@ +#![allow(clippy::unwrap_used, clippy::panic, missing_docs)] + +mod bundle; +#[path = "../common/mod.rs"] +mod common; +mod daemon; +mod env_mode; +mod files_mode; +mod keys_verify; +mod setup; + +use postmaster::adapter::KeyNaming; + +use std::path::Path; +use std::process::Command; + +#[test] +fn fixture_directories_are_private_and_unique() { + use std::os::unix::fs::PermissionsExt; + let first = common::tmpdir("private"); + std::fs::write(first.join("sentinel"), b"retained").unwrap(); + let second = common::tmpdir("private"); + assert_ne!(first.as_path(), second.as_path()); + assert_eq!( + std::fs::metadata(&first).unwrap().permissions().mode() & 0o777, + 0o700 + ); + assert_eq!(std::fs::read(first.join("sentinel")).unwrap(), b"retained"); +} + +#[test] +fn helper_ciphertext_decrypts_with_test_key() { + let v = common::enc("hello $(rm -rf /) `x` \"q\" \nline2"); + let b64 = v.strip_prefix("encrypted:").unwrap(); + let ct = { + use base64::Engine; + base64::engine::general_purpose::STANDARD + .decode(b64) + .unwrap() + }; + let sk = hex::decode(common::TEST_SK_HEX).unwrap(); + let pt = ecies::decrypt(&sk, &ct).unwrap(); + assert_eq!(pt, b"hello $(rm -rf /) `x` \"q\" \nline2"); +} + +#[test] +fn wrapped_base64_ciphertext_decrypts() { + // Test that decrypt_value tolerates ASCII whitespace in base64 payloads, + // matching dotenvx-rs's lenient decoding behavior. + let plaintext = "wrapped-value"; + let v = common::enc(plaintext); + let b64 = v.strip_prefix("encrypted:").unwrap(); + + // Wrap the base64 by inserting newlines every 20 chars + let mut wrapped = String::from("encrypted:"); + for (i, c) in b64.chars().enumerate() { + if i > 0 && i % 20 == 0 { + wrapped.push('\n'); + } + wrapped.push(c); + } + wrapped.push('\n'); + + // Create a temporary keys file with TEST_SK_HEX + let d = common::tmpdir("wrapped-base64"); + common::write_keys_file(&d, "", &[common::TEST_SK_HEX]); + let keys_path = d.join(".env.keys"); + + // Load the key ring + let ring = postmaster::keys::KeyRing::load(&keys_path, &[KeyNaming::Env]).unwrap(); + + // Create a dummy env file path for error messages + let dummy_env = d.join(".env"); + + // decrypt_value should handle the wrapped (whitespace-containing) payload + let result = + postmaster::keys::decrypt_value(&dummy_env, "TEST_VAR", &wrapped, &ring, KeyNaming::Env); + + assert!(result.is_ok(), "wrapped base64 should decrypt successfully"); + let decrypted = result.unwrap(); + assert_eq!(decrypted.as_slice(), plaintext.as_bytes()); +} + +fn run_exec(config: &Path, sh: &str, envs: &[(&str, &str)]) -> std::process::Output { + let mut c = Command::new(env!("CARGO_BIN_EXE_postmaster")); + c.args(["exec", "--config"]) + .arg(config) + .args(["--", "/bin/sh", "-c", sh]) + // Hermeticity: an ambient SECRET/PLAIN/A/GOOD/BAD/SECRET_GOOD in the test + // runner's own environment would flip the precedence-test outcomes below, since + // these are exactly the value-variable names the suite asserts on. + // DOTENV_PUBLIC_KEY_PRODUCTION and POSTMASTER_SECRETS_DIR are asserted ABSENT + // in the child; an ambient copy would be inherited and flake those assertions. + .env_remove("SECRET") + .env_remove("PLAIN") + .env_remove("FIRST") + .env_remove("LAST") + .env_remove("A") + .env_remove("GOOD") + .env_remove("BAD") + .env_remove("SECRET_GOOD") + .env_remove("DOTENV_PUBLIC_KEY_PRODUCTION") + .env_remove("POSTMASTER_SECRETS_DIR"); + for (k, v) in envs { + c.env(k, v); + } + c.output().unwrap() +} + +fn write_config(dir: &Path, json: &str) -> std::path::PathBuf { + let p = dir.join("exec.json"); + std::fs::write(&p, json).unwrap(); + p +} diff --git a/tests/exec_conformance/setup.rs b/tests/exec_conformance/setup.rs new file mode 100644 index 0000000..530fe0e --- /dev/null +++ b/tests/exec_conformance/setup.rs @@ -0,0 +1,185 @@ +//! Exercise real setup input and rotation, including terminal interruption. + +#[path = "../../src/test_util/pty.rs"] +mod pty; + +use std::io::{Read as _, Write as _}; +use std::os::unix::fs::PermissionsExt as _; +use std::process::{Command, Stdio}; + +use crate::common; + +fn setup_command(dir: &std::path::Path, force: bool) -> Command { + let config = dir.join("setup.json"); + std::fs::write(&config, serde_json::json!({"mode":"env", "keys":[{"file":dir.join(".env.keys")}], "env_files":[dir.join(".env")]}).to_string()).unwrap(); + let mut command = Command::new(env!("CARGO_BIN_EXE_postmaster")); + command + .args(["setup", "--config"]) + .arg(config) + .arg("--keys-dir") + .arg(dir.join("provisioning")); + if force { + command.arg("--force"); + } + command +} + +#[test] +fn file_input_hides_secrets_and_restores_echo_before_termination() { + for force in [false, true] { + for interrupt in [false, true] { + let dir = common::tmpdir("setup-tty"); + if force { + common::write_keys_file(&dir, "", &[common::TEST_SK_HEX]); + } + let mut pty = pty::TestPty::new(); + let original = rustix::termios::tcgetattr(&pty.slave).unwrap().local_modes; + pty.spawn(&mut setup_command(&dir, force)); + pty.expect("[y/N]"); + pty.send(b"y\n"); + pty.expect("Paste the keys file contents"); + assert!( + !rustix::termios::tcgetattr(&pty.slave) + .unwrap() + .local_modes + .contains(rustix::termios::LocalModes::ECHO) + ); + if interrupt { + pty.send(b"PRIVATE_SENTINEL\n"); + pty.signal(rustix::process::Signal::TERM); + } else { + pty.send( + format!( + "# PRIVATE_SENTINEL\nDOTENV_PRIVATE_KEY={}\n", + common::TEST_SK_HEX + ) + .as_bytes(), + ); + pty.send(&[4]); + } + assert_eq!( + pty.wait().success(), + !interrupt, + "{}", + String::from_utf8_lossy(&pty.output) + ); + assert_eq!( + rustix::termios::tcgetattr(&pty.slave).unwrap().local_modes, + original + ); + assert!(!String::from_utf8_lossy(&pty.output).contains("PRIVATE_SENTINEL")); + if interrupt && !force { + assert!(!dir.join(".env.keys").exists()); + } + } + } +} + +#[test] +fn rotation_rejects_inode_substitution_after_confirmation() { + let dir = common::tmpdir("rotation-swap"); + let keys = common::write_keys_file(&dir, "", &[common::TEST_SK_HEX]); + let target = dir.join("sentinel"); + std::fs::write(&target, b"untouched").unwrap(); + let mut pty = pty::TestPty::new(); + pty.spawn(&mut setup_command(&dir, true)); + pty.expect("[y/N]"); + pty.send(b"y\n"); + pty.expect("Paste the keys file contents"); + std::fs::rename(&keys, dir.join("original")).unwrap(); + std::os::unix::fs::symlink(&target, &keys).unwrap(); + pty.send(format!("DOTENV_PRIVATE_KEY={}\n", "22".repeat(32)).as_bytes()); + pty.send(&[4]); + assert!(!pty.wait().success()); + assert_eq!(std::fs::read(&target).unwrap(), b"untouched"); + assert!(String::from_utf8_lossy(&pty.output).contains("changed while awaiting input")); +} + +#[test] +fn partial_noncanonical_input_does_not_delay_terminal_restoration() { + use rustix::termios::{LocalModes, OptionalActions, SpecialCodeIndex, tcgetattr, tcsetattr}; + let dir = common::tmpdir("raw-input"); + let mut pty = pty::TestPty::new(); + let mut original = tcgetattr(&pty.slave).unwrap(); + original.local_modes.remove(LocalModes::ICANON); + original.special_codes[SpecialCodeIndex::VMIN] = 1; + original.special_codes[SpecialCodeIndex::VTIME] = 0; + tcsetattr(&pty.slave, OptionalActions::Now, &original).unwrap(); + pty.spawn(&mut setup_command(&dir, false)); + pty.expect("[y/N]"); + pty.send(b"y\n"); + pty.expect("Paste the keys file contents"); + pty.send(b"PRIVATE_SENTINEL"); + std::thread::sleep(std::time::Duration::from_millis(100)); + pty.signal(rustix::process::Signal::TERM); + assert!(!pty.wait().success()); + assert_eq!( + tcgetattr(&pty.slave).unwrap().local_modes, + original.local_modes + ); + assert!(!String::from_utf8_lossy(&pty.output).contains("PRIVATE_SENTINEL")); + assert!(!dir.join(".env.keys").exists()); +} + +#[test] +fn interrupted_canonical_input_is_discarded_before_the_next_reader() { + let dir = common::tmpdir("canonical-interrupt"); + let mut pty = pty::TestPty::new(); + let original = rustix::termios::tcgetattr(&pty.slave).unwrap().local_modes; + assert!(original.contains(rustix::termios::LocalModes::ICANON)); + pty.spawn(&mut setup_command(&dir, false)); + pty.expect("[y/N]"); + pty.send(b"y\n"); + pty.expect("Paste the keys file contents"); + pty.send(b"PRIVATE_SENTINEL"); + pty.signal(rustix::process::Signal::TERM); + assert!(!pty.wait().success()); + assert_eq!( + rustix::termios::tcgetattr(&pty.slave).unwrap().local_modes, + original + ); + // Complete the next canonical line; it must contain none of the interrupted secret. + pty.send(b"\n"); + let mut next = [0; 128]; + let count = pty.slave.read(&mut next).unwrap(); + assert_eq!(&next[..count], b"\n"); + assert!(!dir.join(".env.keys").exists()); +} + +#[test] +fn redirected_rotation_preserves_old_handles_and_read_only_files() { + for mode in [0o400, 0o600] { + let dir = common::tmpdir("rotation-pipe"); + let keys = common::write_keys_file(&dir, "", &[common::TEST_SK_HEX]); + std::fs::set_permissions(&keys, std::fs::Permissions::from_mode(mode)).unwrap(); + let old = std::fs::read(&keys).unwrap(); + let mut handle = std::fs::File::open(&keys).unwrap(); + let mut child = setup_command(&dir, true) + .stdin(Stdio::piped()) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()) + .spawn() + .unwrap(); + let contents = format!("DOTENV_PRIVATE_KEY={}\n", "22".repeat(32)); + child + .stdin + .take() + .unwrap() + .write_all(format!("y\n{contents}").as_bytes()) + .unwrap(); + let output = child.wait_with_output().unwrap(); + assert!( + output.status.success(), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let mut retained = Vec::new(); + handle.read_to_end(&mut retained).unwrap(); + assert_eq!(retained, old); + assert_eq!(std::fs::read(&keys).unwrap(), contents.as_bytes()); + assert_eq!( + std::fs::metadata(&keys).unwrap().permissions().mode() & 0o777, + 0o600 + ); + } +}