Merge pull request #473 from p2pool-starter-stack/release/v1.4.0

release: v1.4.0

Author: VijitSingh97

.gitignore

@@ -1,12 +1,16 @@
 # Secrets and Env
 .env
 .env.new
+.env.dryrun
 .env.apply-incomplete
 config.json
+config.json.bak-control
 /data/
 /build/monero/bitmonero.conf
 /build/tari/config.toml
 Caddyfile
+# One-time first-run epilogue marker (#384), dropped beside .env at runtime.
+.pithead-first-run-done
 # pithead backup archives bundle .env, config.json, the Caddyfile, and the Tor onion private keys
 # into one tarball; secret scanners can't see inside a gzipped tar, so keep the whole dir out (#369).
 /backups/

.gitleaks.toml

@@ -5,9 +5,10 @@ useDefault = true
 [allowlist]
 description = "Accepted false positives"
 regexTarget = "line"
-# curl auth assembled from shell ENV VARS (e.g. `-u "${USER:-}:${PASS:-}"`) is not a hardcoded
+# curl auth assembled from shell ENV VARS (e.g. `-u "${USER:-}:${PASS:-wallet}"`) is not a hardcoded
 # secret — the upstream `curl-auth-user` rule can't distinguish `${VAR}` from a literal credential.
-# This pattern only matches env-var expansions, so a real `-u "admin:hunter2"` is still caught.
+# Both sides must be `${VAR:-default}` expansions (default optional), so a real `-u "admin:hunter2"`
+# is still caught.
 regexes = [
-  '''-u "\$\{[A-Z_]+:-\}:\$\{[A-Z_]+:-\}"''',
+  '''-u "\$\{[A-Z_]+:-[^}]*\}:\$\{[A-Z_]+:-[^}]*\}"''',
 ]

CHANGELOG.md

@@ -0,0 +1,87 @@
+<!-- markdownlint-disable -->
+<!-- Verbatim Contributor Covenant v2.1 (https://www.contributor-covenant.org/version/2/1/code_of_conduct/);
+     only the enforcement contact is filled in. Do not reword — markdownlint and docs-voice are disabled here. -->
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement via GitHub's private vulnerability reporting (the **Security** tab → **Report a vulnerability**), the same private channel described in [SECURITY.md](SECURITY.md). All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CODE_OF_CONDUCT.md

@@ -8,6 +8,7 @@ The workflow for contributing bug fixes, docs changes, and features.
   there first.
 - Check the [open issues](https://github.com/p2pool-starter-stack/pithead/issues) for existing
   work on the same thing.
+- This project follows a [Code of Conduct](CODE_OF_CONDUCT.md); by participating you agree to uphold it.
 
 ## Dev environment
 
@@ -36,11 +37,12 @@ runs `ruff` (plus a few hygiene hooks) on your changed files. If you change depe
    make test
    ```
 
-   This runs everything CI does without a server or Docker:
+   This runs everything CI does that doesn't need a live test server:
 
    - **lint** — every file surface gets a linter/formatter check (`make lint` runs them all; run one
      with `make lint-<surface>`): `lint-sh` (shellcheck + shfmt), `lint-py` (ruff), `lint-js` (Biome),
-     `lint-yaml` (yamllint), `lint-md` (markdownlint), `lint-proto` (buf), `lint-toml` (taplo). The
+     `lint-yaml` (yamllint), `lint-md` (markdownlint), `lint-docs-voice` (banned-word check),
+     `lint-proto` (buf), `lint-toml` (taplo). The
      non-Python tools run via `npx`/`uvx`/`docker`, so a contributor needs **Node, uv, and Docker**
      on PATH (plus `shfmt`); `pre-commit` runs the same checks on changed files. Link-checking
      (`lychee`) runs on a weekly schedule, not per-PR.

CONTRIBUTING.md

@@ -39,9 +39,9 @@ test-integration: ## Run the live config-matrix integration suite (requires a te
 lint: lint-sh lint-py lint-js lint-yaml lint-md lint-docs-voice lint-proto lint-toml ## Lint/format-check every surface
 
 lint-sh: ## shellcheck + shfmt over the CLI, build/* container scripts, release + test scripts
-	shellcheck --severity=warning pithead scripts/*.sh build/*/*.sh tests/stack/run.sh tests/stack/test_compose.sh \
+	shellcheck --severity=warning pithead pithead-completion.bash scripts/*.sh build/*/*.sh tests/stack/run.sh tests/stack/test_compose.sh \
 		tests/inventory.sh tests/integration/*.sh tests/integration/mini-stack/*.sh
-	shfmt -i 4 -d pithead $(shell git ls-files '*.sh')
+	shfmt -i 4 -d pithead pithead-completion.bash $(shell git ls-files '*.sh')
 
 lint-py: ## ruff lint + format check on all repo Python (ruff runs via uv from the locked dev extra)
 	uv run --locked --project build/dashboard --extra dev ruff check .

Makefile

@@ -36,8 +36,11 @@ a Tor daemon. The `pithead` script renders config, provisions Tor, and drives do
   guide](docs/privacy.md) maps every connection.
 - 🔌 **One endpoint for every rig.** Point all workers at a single address on port `3333`. No wallet
   address in the miner config; the stack routes the hashrate.
-- 📊 **Live dashboard.** Hashrate, the P2Pool/XvB split, the PPLNS window, and per-worker updates,
-  served over HTTPS on your LAN.
+- 📊 **Live dashboard, now with config editing.** Hashrate, the P2Pool/XvB split, the PPLNS window,
+  and per-worker updates over HTTPS on your LAN. Opt in with `dashboard.control.enabled` to edit
+  `config.json`, one-click upgrade to a new release, and watch the access + config-change audit logs
+  from the browser — every change gated host-side behind a login. See
+  [The Dashboard](docs/dashboard.md).
 - 📟 **Telegram operator bot.** Opt-in alerts for a downed node, a worker that dropped off, sync
   finishing, low disk, a clearnet leak, or a sustained hashrate drop — plus a daily digest and
   read-only commands (`/status`, `/hashrate`, `/workers`, `/earnings`). Routed over Tor. See the
@@ -98,7 +101,7 @@ Full walkthrough: [docs/getting-started.md](docs/getting-started.md)
 | **[Getting Started](docs/getting-started.md)** | Prerequisites, install, first-run setup, and what to expect while the node syncs. |
 | **[Hardware Requirements](docs/hardware.md)** | Minimum vs. recommended specs for the stack host (CPU, RAM, disk, network), and how to run leaner. (Miner specs live in [RigForge](https://github.com/p2pool-starter-stack/rigforge).) |
 | **[Configuration](docs/configuration.md)** | Every `config.json` key, applying changes safely, reusing an existing node, and remote Monero nodes. |
-| **[The Dashboard](docs/dashboard.md)** | Sync Mode and a tour of the live operational view. |
+| **[The Dashboard](docs/dashboard.md)** | Sync Mode, a tour of the live operational view, and the opt-in control channel: editing config, one-click upgrades, and the audit logs from the browser. |
 | **[Connecting Miners](docs/workers.md)** | Point any existing rig at the stack, or spin up a tuned miner with [RigForge](https://github.com/p2pool-starter-stack/rigforge). |
 | **[Architecture](docs/architecture.md)** | The nine services, the privacy model, and the algorithmic XvB switching engine. |
 | **[Privacy & Network Egress](docs/privacy.md)** | Every off-box connection: what's Tor-routed, what's clearnet today, and how to harden it. |
@@ -191,8 +194,15 @@ Everything runs through `pithead` (`./pithead help` lists it all):
 | `./pithead logs [service]` | Follow logs (all, or one service). |
 | `./pithead status` | Container status + health-check of every expected service (warns on anything down). |
 | `./pithead doctor` | Read-only health report (deps, Docker, AVX2, HugePages, RAM/disk, onion state). |
-| `./pithead backup` | Save config, secrets, the Tor onion keys, and the dashboard's database to `backups/` (`--with-chains` adds blockchain data; `-y` / `--yes` skips the prompts). |
-| `./pithead restore <archive>` | Restore those files from a backup archive (asks before overwriting; `-y` / `--yes` skips the prompt). |
+| `./pithead version` | Print the installed stack version on one line (offline; also `-V` / `--version`). |
+| `./pithead backup` | Save config, secrets, the Tor onion keys, and the dashboard's database to a passphrase-encrypted archive under `backups/` (`--with-chains` adds blockchain data; `--no-encrypt` writes plaintext; `-y` / `--yes` skips the prompts). |
+| `./pithead restore <archive>` | Restore those files from a backup archive, encrypted or plaintext (asks before overwriting; `-y` / `--yes` skips the prompt). |
+| `./pithead rotate-secrets` | Regenerate the stack's internal credentials after a suspected leak — see [Rotating the internal secrets](docs/operations.md#rotating-the-internal-secrets). |
+
+Commands chain in one call (`./pithead apply upgrade` runs both, stopping on the first failure;
+nonsense like `up down` is rejected before anything runs), and `source pithead-completion.bash`
+adds bash/zsh tab-completion — see
+[Operations › Chaining commands](docs/operations.md#chaining-commands).
 
 Full reference: **[Operations & Maintenance](docs/operations.md)**.
 

README.md

@@ -39,9 +39,62 @@ The stack's defaults:
   run with `no-new-privileges` and drop all Linux capabilities; internet-facing and
   Docker-socket-facing services also use a read-only root filesystem.
 - SHA256-verified, version-pinned binaries.
+- Signed releases, verified before upgrade
+  ([#376](https://github.com/p2pool-starter-stack/pithead/issues/376)): every published image
+  digest and the install bundle carry a cosign key signature made on the release box; only the
+  public key (`cosign.pub`) is committed, and it ships in every bundle. `pithead upgrade` and the
+  dashboard's one-click upgrade verify against it before anything is pulled or extracted, and fail
+  closed while a key is present — a bad signature, a stripped `.sig`, or a missing cosign binary
+  aborts the upgrade. The bundle check anchors trust in the key *already on disk*, so a malicious
+  bundle cannot vouch for itself with a swapped key, and because a signature binds bytes rather
+  than a version, the dashboard upgrade also refuses a bundle whose own `VERSION` does not match
+  the requested tag — closing a rollback to an older, validly-signed release. Limits: installs
+  without `cosign.pub` (releases before signing landed) upgrade unverified with a warning; a
+  compromise of the release box itself — which holds the private key — is outside what a signature
+  can prove; and the CLI image-verify checks the tag, then pulls it in a separate step (a
+  verify-then-pull window tracked as a follow-up). See
+  [Releasing › Signed releases](docs/releasing.md#signed-releases).
 - Localhost-only RPC.
 - LAN-scoped (and narrowable) stratum port.
 - Scoped Docker socket proxies.
 - Tor for all node networking.
+- A one-way host-control boundary for dashboard config editing and upgrades (`dashboard.control`,
+  default off): the dashboard container can only *ask* — it writes typed JSON intents into a spool
+  directory whose other legs (staged configs, results, the audit log) are host-owned and mounted
+  read-only. A root systemd unit re-validates every intent with pithead's own config validation
+  and dispatches exactly three fixed actions (`apply --dry-run`, `apply -y`, and a release
+  upgrade); no string from the container is ever executed. The upgrade intent carries only the
+  version the operator confirmed: the runner re-derives the target itself from the GitHub release
+  API (over the stack's Tor SOCKS), refuses any mismatch or non-release tag, and limits attempts
+  to one per 10 minutes — the container cannot choose an image, tag, or registry. Enabling the
+  channel without a dashboard password is a validation error, on a published onion it additionally
+  requires Tor client authorization, and every mutation is audited host-side. Commits are default-denied against an explicit allowlist of
+  operational settings: a commit that changes any env key off that list — in every direction
+  (enabling, changing, or disabling) — is refused, as is anything the change preview flags
+  destructive. Wallets, dashboard auth and onion exposure, the control channel itself, the Tor
+  egress firewall, clearnet toggles, node endpoints, binds, and every credential are off the
+  list, and a key added in the future stays un-committable until deliberately listed. Those
+  edits must be applied from the host CLI; out-of-band approval is tracked in
+  [#338](https://github.com/p2pool-starter-stack/pithead/issues/338).
+- Attack visibility (#349): Caddy writes a JSON access log for every dashboard vhost (LAN and
+  onion), and the control channel's host-side audit log records who changed what (setting names
+  only, never values). The dashboard surfaces both read-only — a burst of 401s is the
+  rotate-the-password signal — and treats every logged field as hostile input: strings are
+  whitelisted to a safe character set before display, because the access log echoes
+  attacker-chosen bytes (request paths, attempted usernames) and rendering them raw would hand an
+  anonymous prober stored XSS against the operator. Both logs are size-bounded (Caddy's native
+  rolling; a trim-before-append cap in the audit writer). Neither ever records a secret: Caddy
+  redacts credential headers by default, and the audit writer logs key names only.
+
+### Secret trust boundary for dashboard config editing
+
+When `dashboard.control` is on, the dashboard reads `config.json` through a **read-only bind
+mount** to prefill the editor form. The API masks every secret leaf before serving it to the
+browser — but that masking protects the *browser*, not the container. The bind mount itself is the
+real secret boundary: a backend compromise of the dashboard container can read the plaintext
+`config.json` (including the dashboard login and stratum passwords) directly off the mount,
+regardless of the API masking. Treat the dashboard container as semi-trusted, keep the onion behind
+Tor client authorization, and do not co-host untrusted workloads in that container. Host-side
+staged copies that carry merged secrets are written mode 600.
 
 Report any gap in these.

SECURITY.md

@@ -1 +1 @@
-1.3.1
+1.4.0