Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
47 commits
Select commit Hold shift + click to select a range
6c6cf19
security: remediate 2026-08-02 audit (33/33 findings), bind bundle en…
beardedeagle Aug 5, 2026
90df6fb
nix: fill cargoLock.outputHashes for the git-pinned ecies dep
beardedeagle Aug 5, 2026
659e548
docs: sweep for statements made stale by the 2026-08-02 audit remedia…
beardedeagle Aug 5, 2026
6fdb5af
docs: remove stale mdbook-build-issue.md scratch note
beardedeagle Aug 5, 2026
5aee321
deps: fold open dependabot PRs — base64 0.23 + minor-patch group
beardedeagle Aug 5, 2026
3004c8b
ci: conform automation to the repo doctrine (just = single source of …
beardedeagle Aug 5, 2026
5e24638
refactor: split over-limit files and group modules by domain
beardedeagle Aug 5, 2026
0d92689
docs: add Unsafe Code section (policy + registry of every unsafe site)
beardedeagle Aug 5, 2026
dae7fa1
lints: adopt multiple_crate_versions (clippy) + deny.toml bans companion
beardedeagle Aug 5, 2026
b011cda
review: address PR #6 review — 18 fixes, 1 rebuttal, 1 documented res…
beardedeagle Aug 5, 2026
776cbd0
docs: move the signal pending/exec race residual to the threat model
beardedeagle Aug 5, 2026
a032262
fix(launcher): close the termination-signal check/exec race (A11 foll…
beardedeagle Aug 5, 2026
2841cfa
fix(launcher): second termination-flag gate immediately before execvp
beardedeagle Aug 6, 2026
613935e
feat(launcher): sibling launch monitor — per-service supervision and …
beardedeagle Aug 6, 2026
7be71fe
test: serialize env-mutating tests on one process-wide ENV_LOCK
beardedeagle Aug 6, 2026
e1f1c21
fix: admit config-required key namings into the key ring
beardedeagle Aug 6, 2026
86e5a6c
docs: single-tenant secrets_dir contract for hand-written configs
beardedeagle Aug 6, 2026
9f970cb
fix(keys): redact Debug on secret types; tighten source/verify parity
beardedeagle Aug 7, 2026
e26cce6
fix(provisioning): make --force real (re-seed, re-prompt) instead of …
beardedeagle Aug 7, 2026
7d97882
fix(launcher): ramdisk containment, macOS guard failure path, bundle …
beardedeagle Aug 7, 2026
6d83eec
fix(server): peer_user ACL is never overridden; startup hardening gap…
beardedeagle Aug 7, 2026
850016b
refactor(cli): help/usage accuracy, flag-swallow guard, harden only s…
beardedeagle Aug 7, 2026
f907ff2
fix(schema): align exec.schema.json with the parser (bundle_files)
beardedeagle Aug 7, 2026
104752c
test: regression coverage for audit seams (T3-T16)
beardedeagle Aug 7, 2026
866883a
fix(server): darwin socket perms via bind-time umask (T2)
beardedeagle Aug 7, 2026
a2f2318
refactor(monitor): extract tests to src/monitor/tests.rs (X8)
beardedeagle Aug 7, 2026
0341deb
docs: factual corrections across the book and README (O-group)
beardedeagle Aug 7, 2026
5475505
chore(repo): justfile gates, toolchain targets, nix naming, ignore cl…
beardedeagle Aug 7, 2026
15c5072
chore(ci): pin tool versions, wire lint-md, gate deny/audit in hooks
beardedeagle Aug 7, 2026
1860d84
docs: at-a-glance layer, monitor lifecycle diagram, pipeline dedup
beardedeagle Aug 7, 2026
1bbe63d
docs: executive overview page for leadership and PM audiences
beardedeagle Aug 7, 2026
fadcc6d
docs(changelog): record the 2026-08-07 clean sweep + e1f1c21 (O27)
beardedeagle Aug 7, 2026
9550ec1
fix: isolate launch keys and own bundle AAD decoding
beardedeagle Nov 8, 2026
31a3d86
fix: retain verified RAM-disk handles during launch
beardedeagle Nov 8, 2026
cb4a607
docs: describe 0.1.0 as the first planned release
beardedeagle Nov 8, 2026
421a593
fix: redact key-file errors and synchronize monitor tests
beardedeagle Nov 8, 2026
f16e07b
fix: enforce socket modes and setup tool versions
beardedeagle Nov 8, 2026
b530668
fix: secure secret input and materialization boundaries
beardedeagle Nov 8, 2026
b76a780
fix: validate key access and restore terminal input safely
beardedeagle Nov 8, 2026
949a0f4
fix: deduplicate setup keys and enable Nix features
beardedeagle Nov 9, 2026
f55ad35
docs: align runtime guidance and documentation voice
beardedeagle Nov 10, 2026
3129096
docs: correct runtime dependency descriptions
beardedeagle Nov 10, 2026
4fa0607
docs: fix mermaid diagram rendering across the book
beardedeagle Nov 10, 2026
9bd5fb4
fix: isolate monitor tests and refresh crypto dependencies
beardedeagle Nov 10, 2026
3b46f74
fix: refresh stable Rust before CI setup checks
beardedeagle Nov 10, 2026
aaa263f
ci: enable hosted quality, security, Nix and docs checks
beardedeagle Nov 10, 2026
837df44
test: assert fail-closed behavior in isolated builds
beardedeagle Nov 10, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,3 @@
*.ico binary
*.exe binary
*.zip binary
docs/book/ binary
91 changes: 91 additions & 0 deletions .github/CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -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 <randy@heroictek.com>.**

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).
51 changes: 27 additions & 24 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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
Expand All @@ -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.
3 changes: 2 additions & 1 deletion .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
23 changes: 10 additions & 13 deletions .github/SECURITY.md
Original file line number Diff line number Diff line change
@@ -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 <randy@heroictek.com>.

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.
55 changes: 55 additions & 0 deletions .github/actions/setup-nix/action.yml
Original file line number Diff line number Diff line change
@@ -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
47 changes: 47 additions & 0 deletions .github/actions/setup-nix/test.py
Original file line number Diff line number Diff line change
@@ -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")
Loading
Loading