clauster 0.2.0__tar.gz → 0.2.2__tar.gz

{clauster-0.2.0 → clauster-0.2.2}/.bestpractices.json

@@ -37,12 +37,12 @@
   "version_unique_justification": "Each release has a unique Semantic Version identifier maintained in pyproject.toml and src/clauster/__init__.py, which makes every build uniquely identifiable. Release tagging is automated via release-please (.release-please-manifest.json / release-please-config.json) and produces a vX.Y.Z git tag when a release is published.",
   "version_semver_status": "Met",
   "version_semver_justification": "The project uses Semantic Versioning (MAJOR.MINOR.PATCH).",
-  "version_tags_status": "Unmet",
-  "version_tags_justification": "No release has been cut yet, so no semantic-version git tags exist. Tagging is configured and automated via release-please and will produce vX.Y.Z tags once the first release is published.",
-  "release_notes_status": "N/A",
-  "release_notes_justification": "No release has been published, so there are no release notes to provide. Releases are published through the release-please workflow, which generates human-readable, grouped release notes (a CHANGELOG entry and a tagged GitHub Release) from the Conventional Commit history.",
+  "version_tags_status": "Met",
+  "version_tags_justification": "Releases are cut as semantic-version git tags by the automated release-please workflow. Published tags include v0.2.0 and v0.2.1 (https://github.com/schubydoo/clauster/tags), each tagging the corresponding release commit on main.",
+  "release_notes_status": "Met",
+  "release_notes_justification": "Each release provides human-readable release notes: release-please generates a curated, grouped CHANGELOG.md entry (https://github.com/schubydoo/clauster/blob/main/CHANGELOG.md) and a matching tagged GitHub Release (e.g. v0.2.0, v0.2.1 at https://github.com/schubydoo/clauster/releases) from the Conventional Commit history, organized into Features / Bug Fixes sections. These are a curated summary, not the raw version-control log.",
   "release_notes_vulns_status": "N/A",
-  "release_notes_vulns_justification": "No release has shipped a security fix and no publicly-known vulnerability has required disclosure. When a release fixes one, release-please records it in the generated release notes (Bug Fixes section).",
+  "release_notes_vulns_justification": "No published release has fixed a publicly-known (e.g. CVE-assigned) run-time vulnerability, so there is nothing to identify in the release notes. When a release does fix one, release-please records it in the generated notes (Bug Fixes section) and this would become Met.",
   "report_process_status": "Met",
   "report_process_justification": "Bugs are reported via GitHub Issues; security issues via SECURITY.md. https://github.com/schubydoo/clauster/issues",
   "report_tracker_status": "Met",

{clauster-0.2.0 → clauster-0.2.2}/.github/workflows/lint.yml

@@ -43,10 +43,10 @@ jobs:
       # drifts across image refreshes) and install the version-pinned, integrity-
       # checked package from the lockfile via `npm ci`. yamllint comes from
       # `uv sync --extra dev` above.
-      - name: Set up Node 20
+      - name: Set up Node 24
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: "20"
+          node-version: "24"
           cache: npm
       - name: Install Node deps
         run: npm ci

clauster-0.2.2/.github/workflows/release-please.yml

@@ -0,0 +1,139 @@
+name: Release Please
+
+# Release Please reads Conventional Commits on main and opens a "release PR"
+# that bumps the version (src/clauster/__init__.py + pyproject.toml) and rewrites
+# CHANGELOG.md. Merging that PR tags the commit (e.g. `v0.2.0`), which fires
+# release.yml (`on: push: tags`).
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-please-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # GITHUB_TOKEN stays read-only: the App token (minted below) does all the
+    # writing, so the default token needs no write scope here.
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      # Mint a short-lived installation token for the Clauster release GitHub
+      # App so the release PR + version-bump commits are authored by the app's
+      # bot identity, NOT a human account. Crucially this is *not* the default
+      # GITHUB_TOKEN, so the tag pushed when the release PR merges still
+      # *triggers* release.yml (GITHUB_TOKEN-pushed tags don't — anti-recursion).
+      #
+      # Requires (set up once, manually):
+      #   - a GitHub App owned by the repo owner, installed on this repo, with
+      #     repo permissions Contents: R/W + Pull requests: R/W;
+      #   - secrets RELEASE_PLEASE_APP_ID (numeric App ID) and
+      #     RELEASE_PLEASE_APP_PRIVATE_KEY (the App's .pem private key).
+      # Until those exist this step 401s — merge this only after they're added.
+      # Supersedes the old RELEASE_PLEASE_TOKEN PAT (which attributed PRs to a
+      # real user); that secret can be deleted once this is live.
+      - name: Mint GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.RELEASE_PLEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_PLEASE_APP_PRIVATE_KEY }}
+          # Scope the minted token to exactly what release-please needs, rather
+          # than inheriting the installation's full permission set (zizmor
+          # least-privilege). Add permission-issues: write only if you enable
+          # release-please's label-on-issue features.
+          permission-contents: write
+          permission-pull-requests: write
+
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # --- Keep uv.lock's editable self-version in sync with the release bump ---
+      # release-please bumps pyproject.toml's version but NOT uv.lock, so the lock's
+      # `[[package]] name = "clauster"` version drifts behind each release — a
+      # papercut where every local `uv` run then regenerates uv.lock into a stray
+      # diff. When a release PR is open, regenerate uv.lock on that PR branch so the
+      # lock bumps together with pyproject and lands in the same merge. A no-op on
+      # every other push (and when the lock is already in sync). It pushes only to
+      # the bot's own `release-please--*` branch, never to main.
+      - name: Detect open release PR
+        id: relpr
+        env:
+          GH_TOKEN: ${{ github.token }} # read-only default token is enough for `pr list`
+        run: |
+          set -euo pipefail
+          # Pick the release PR by *authenticated identity*, not just the branch
+          # name: it must be authored by the release App, target main, and be an
+          # in-repo (non-fork) branch. The branch-name prefix alone would let any
+          # collaborator open a `release-please--*` PR and have us check it out +
+          # run `uv lock` (which can execute the project's build backend) in this
+          # trusted push context with the app token in scope. gh renders an App
+          # author as `app/<slug>`.
+          branch="$(gh pr list --repo "$GITHUB_REPOSITORY" --state open \
+            --json headRefName,baseRefName,author,isCrossRepository \
+            --jq '[.[]
+                   | select(.headRefName | startswith("release-please--"))
+                   | select(.baseRefName == "main")
+                   | select(.isCrossRepository == false)
+                   | select(.author.login == "app/clauster-release-bot")
+                  ][0].headRefName // ""')"
+          echo "branch=$branch" >> "$GITHUB_OUTPUT"
+          if [ -n "$branch" ]; then echo "Release PR branch: $branch"; else echo "No open release PR."; fi
+
+      - name: Check out repo
+        if: ${{ steps.relpr.outputs.branch != '' }}
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up uv
+        if: ${{ steps.relpr.outputs.branch != '' }}
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          # No cache: this job can push, and setup-uv's default caching is a
+          # cache-poisoning vector (zizmor). A one-off `uv lock` doesn't need it.
+          enable-cache: false
+
+      - name: Sync uv.lock on the release PR
+        if: ${{ steps.relpr.outputs.branch != '' }}
+        env:
+          # App token (contents: write) so the push is authorized AND keeps the
+          # release PR bot-authored. Branch via env (not inlined) — no injection.
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          PR_BRANCH: ${{ steps.relpr.outputs.branch }}
+        run: |
+          set -euo pipefail
+          # Defensive: only ever touch the bot's release branch, never anything else.
+          case "$PR_BRANCH" in
+            release-please--*) ;;
+            *) echo "refusing to push to unexpected branch '$PR_BRANCH'"; exit 1 ;;
+          esac
+          git fetch --quiet origin "$PR_BRANCH"
+          git checkout -B "$PR_BRANCH" FETCH_HEAD
+          uv lock
+          if git diff --quiet -- uv.lock; then
+            echo "uv.lock already in sync — nothing to commit."
+            exit 0
+          fi
+          # Attribute the commit to the release bot (fall back to the Actions bot).
+          bot_user="clauster-release-bot[bot]"
+          bot_id="$(gh api "/users/${bot_user}" --jq '.id' 2>/dev/null || true)"
+          if [ -z "$bot_id" ]; then bot_user="github-actions[bot]"; bot_id="41898282"; fi
+          git config user.name "$bot_user"
+          git config user.email "${bot_id}+${bot_user}@users.noreply.github.com"
+          git add uv.lock
+          git commit -m "chore: sync uv.lock to the release version"
+          git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "HEAD:${PR_BRANCH}"
+          echo "Pushed uv.lock sync to $PR_BRANCH."

clauster-0.2.2/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.2"
+}

{clauster-0.2.0 → clauster-0.2.2}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.2.2](https://github.com/schubydoo/clauster/compare/v0.2.1...v0.2.2) (2026-06-03)
+
+
+### Security
+
+* **This is a security release.** A non-loopback bind (e.g. `0.0.0.0` or a LAN IP) could serve the dashboard **unauthenticated** when `auth.enabled` was left at its default `false` — even with a password configured — because the runtime guard only enforces auth when `auth.enabled` is set, while config validation did not require it. The config validator now refuses to start a non-loopback bind unless authentication is actually enforced (`auth.enabled: true` together with `auth.password_required` + a hash, or `auth.reverse_proxy.enabled`; or the explicit `auth.allow_unauthenticated_network` opt-out). All prior releases (≤ 0.2.1) are affected, including the Docker image. **Upgrade, and on any networked deployment set `auth.enabled: true`.** See [GHSA-h4g2-xfmw-q2c9](https://github.com/schubydoo/clauster/security/advisories/GHSA-h4g2-xfmw-q2c9).
+
+
+### Bug Fixes
+
+* **auth:** refuse non-loopback bind unless auth is actually enforced ([#88](https://github.com/schubydoo/clauster/issues/88)) ([d89d753](https://github.com/schubydoo/clauster/commit/d89d753120c2246eea1838cea9528aa7658eb36f))
+
+## [0.2.1](https://github.com/schubydoo/clauster/compare/v0.2.0...v0.2.1) (2026-06-03)
+
+
+### Documentation
+
+* absolute GitHub URLs in README so images render on PyPI ([#79](https://github.com/schubydoo/clauster/issues/79)) ([1feef42](https://github.com/schubydoo/clauster/commit/1feef42b91a82b2d31063aa448c90e5a0688fb6a))
+
 ## [0.2.0](https://github.com/schubydoo/clauster/compare/v0.1.0...v0.2.0) (2026-06-03)
 
 

{clauster-0.2.0 → clauster-0.2.2}/Dockerfile

@@ -47,7 +47,9 @@ COPY --from=builder /app/.venv /app/.venv
 ENV PATH="/app/.venv/bin:$PATH" \
     PYTHONUNBUFFERED=1 \
     # Bind all interfaces (a container is useless on loopback). host!=loopback
-    # makes clauster REQUIRE auth — set CLAUSTER_AUTH_PASSWORD_HASH or it exits.
+    # makes clauster REQUIRE enforced auth — set CLAUSTER_AUTH_ENABLED=true +
+    # CLAUSTER_AUTH_PASSWORD_REQUIRED=true + CLAUSTER_AUTH_PASSWORD_HASH (or
+    # reverse-proxy trust), or it exits on start. See README "Docker".
     CLAUSTER_HOST=0.0.0.0 \
     CLAUSTER_PORT=7621 \
     CLAUSTER_LOG_FORMAT=json \

{clauster-0.2.0 → clauster-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clauster
-Version: 0.2.0
+Version: 0.2.2
 Summary: Self-hosted web UI for spawning and managing Claude Code remote-control bridges on a remote host.
 Project-URL: Homepage, https://github.com/schubydoo/clauster
 Project-URL: Repository, https://github.com/schubydoo/clauster
@@ -60,14 +60,14 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue.svg">
-  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
+  <a href="https://github.com/schubydoo/clauster/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
   <a href="https://github.com/schubydoo/clauster/pkgs/container/clauster"><img alt="GHCR" src="https://img.shields.io/badge/ghcr.io-clauster-2496ED?logo=docker&logoColor=white"></a>
   <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
   <a href="https://pre-commit.com/"><img alt="pre-commit" src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white"></a>
 </p>
 
 <p align="center">
-  <img src="docs/screenshots/dashboard-dark.png" alt="Clauster dashboard" width="860">
+  <img src="https://raw.githubusercontent.com/schubydoo/clauster/main/docs/screenshots/dashboard-dark.png" alt="Clauster dashboard" width="860">
 </p>
 
 Anthropic's first-party tooling assumes terminal access on the host to spawn a
@@ -83,17 +83,17 @@ a project, start a bridge, and attach to it from `claude.ai/code` or the mobile
 <table>
   <tr>
     <td width="50%" align="center">
-      <img src="docs/screenshots/dashboard-light.png" alt="Dashboard, light theme"><br>
+      <img src="https://raw.githubusercontent.com/schubydoo/clauster/main/docs/screenshots/dashboard-light.png" alt="Dashboard, light theme"><br>
       <sub><b>Dark / light</b> — theme toggle persists across reloads</sub>
     </td>
     <td width="50%" align="center">
-      <img src="docs/screenshots/new-project-clone.png" alt="Create or clone a project"><br>
+      <img src="https://raw.githubusercontent.com/schubydoo/clauster/main/docs/screenshots/new-project-clone.png" alt="Create or clone a project"><br>
       <sub><b>Create or clone</b> — SSRF-guarded, cloned code runs only on Start</sub>
     </td>
   </tr>
   <tr>
     <td width="50%" align="center">
-      <img src="docs/screenshots/login-dark.png" alt="Password login"><br>
+      <img src="https://raw.githubusercontent.com/schubydoo/clauster/main/docs/screenshots/login-dark.png" alt="Password login"><br>
       <sub><b>Password login</b> — for non-loopback / networked deploys</sub>
     </td>
     <td width="50%" align="center" valign="middle">
@@ -107,7 +107,7 @@ a project, start a bridge, and attach to it from `claude.ai/code` or the mobile
 
 Everything below is implemented and shipping. Items marked **(opt-in)** are gated
 behind a config flag and off by default — the flag is named inline so you can find
-it in [`clauster.yml.example`](clauster.yml.example).
+it in [`clauster.yml.example`](https://github.com/schubydoo/clauster/blob/main/clauster.yml.example).
 
 ### Projects & bridges
 
@@ -185,20 +185,33 @@ it; it isn't vendored).
 
 ## Docker
 
-Multi-arch images (`linux/amd64`, `linux/arm64`) are published to GHCR on each release:
+Multi-arch images (`linux/amd64`, `linux/arm64`) are published to GHCR on each release.
+The image binds `0.0.0.0`, so it **requires enforced auth** to start. First generate a
+password hash — this runs `clauster` *inside* the image, so you don't need it on the host:
+
+```sh
+docker run --rm -it ghcr.io/schubydoo/clauster:latest clauster hash-password
+```
+
+Copy the printed `$argon2id$…` hash, then start the server with auth enabled:
 
 ```sh
 docker run -d --name clauster \
   -p 7621:7621 \
   -e PUID=1000 -e PGID=1000 \
-  -e CLAUSTER_AUTH_PASSWORD_HASH="$(clauster hash-password)" \
+  -e CLAUSTER_AUTH_ENABLED=true \
+  -e CLAUSTER_AUTH_PASSWORD_REQUIRED=true \
+  -e 'CLAUSTER_AUTH_PASSWORD_HASH=$argon2id$v=19$...' \
   -v /path/to/config:/config \
   -v /path/to/projects:/projects \
   ghcr.io/schubydoo/clauster:latest
 ```
 
-- The image binds `0.0.0.0`, which **requires auth** — set `CLAUSTER_AUTH_PASSWORD_HASH`
-  (or put it in `/config/clauster.yml`) or the container exits on start.
+- The image binds `0.0.0.0`, so it won't start without **enforced** auth — set
+  `CLAUSTER_AUTH_ENABLED=true` **and** `CLAUSTER_AUTH_PASSWORD_REQUIRED=true` **and** a
+  `CLAUSTER_AUTH_PASSWORD_HASH` (or configure reverse-proxy trust in `/config/clauster.yml`),
+  or the container exits on start. Single-quote the hash env value — the argon2 hash
+  contains `$` that your shell would otherwise expand.
 - `/config` holds `clauster.yml` + state; `/projects` is your `projects_root`.
   `PUID`/`PGID` remap the runtime user to own bind-mounts.
 - `claude` is **not** baked in — tell Clauster where it is one of two ways: mount the
@@ -213,16 +226,17 @@ docker run -d --name clauster \
 ## Auth & networking
 
 Loopback (`127.0.0.1`) needs no auth. Binding to a non-loopback address is refused
-unless you enable one of: password login (`auth.password_required` + a hash from
-`clauster hash-password`), reverse-proxy trust (peer-IP allowlist + HMAC header), or
-an explicit `auth.allow_unauthenticated_network` opt-out for a trusted LAN. Sessions
+unless authentication is actually enforced — set `auth.enabled: true` (the master
+switch) together with either password login (`auth.password_required` + a hash from
+`clauster hash-password`) or reverse-proxy trust (peer-IP allowlist + HMAC header) —
+or, to opt out on a trusted LAN, `auth.allow_unauthenticated_network`. Sessions
 are signed cookies with server-side revocation ("log out everywhere"); WebSocket
 connections are authenticated before accept and origin-checked.
 
 ## Configuration
 
 All settings live in `clauster.yml` — see
-[`clauster.yml.example`](clauster.yml.example) for the full, commented schema. Any
+[`clauster.yml.example`](https://github.com/schubydoo/clauster/blob/main/clauster.yml.example) for the full, commented schema. Any
 scalar key is overridable by an environment variable of the form
 `CLAUSTER_<UPPER_SNAKE_PATH>`. The schema is additive-only — old configs always
 validate against newer versions.
@@ -231,6 +245,7 @@ validate against newer versions.
 | --- | --- | --- |
 | `host` / `port` | `127.0.0.1` / `7621` | bind address (non-loopback needs auth) |
 | `projects_root` | — | directory whose children become project cards |
+| `auth.enabled` | `false` | master auth switch — must be on for password / proxy auth to apply |
 | `auth.password_required` | `false` | require login (`clauster hash-password` for the hash) |
 | `claude.resume_recap` | `false` | recap the prior transcript into a restarted bridge |
 | `claude.resume_mode` | `standard` | `pty` = native true-resume on Restart (POSIX) |
@@ -277,4 +292,4 @@ and CI-gated on Linux; macOS / Windows are in the test matrix. Apache-2.0 licens
 
 ## License
 
-[Apache License 2.0](LICENSE).
+[Apache License 2.0](https://github.com/schubydoo/clauster/blob/main/LICENSE).

{clauster-0.2.0 → clauster-0.2.2}/README.md

@@ -17,14 +17,14 @@
 
 <p align="center">
   <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue.svg">
-  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
+  <a href="https://github.com/schubydoo/clauster/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
   <a href="https://github.com/schubydoo/clauster/pkgs/container/clauster"><img alt="GHCR" src="https://img.shields.io/badge/ghcr.io-clauster-2496ED?logo=docker&logoColor=white"></a>
   <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
   <a href="https://pre-commit.com/"><img alt="pre-commit" src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white"></a>
 </p>
 
 <p align="center">
-  <img src="docs/screenshots/dashboard-dark.png" alt="Clauster dashboard" width="860">
+  <img src="https://raw.githubusercontent.com/schubydoo/clauster/main/docs/screenshots/dashboard-dark.png" alt="Clauster dashboard" width="860">
 </p>
 
 Anthropic's first-party tooling assumes terminal access on the host to spawn a
@@ -40,17 +40,17 @@ a project, start a bridge, and attach to it from `claude.ai/code` or the mobile
 <table>
   <tr>
     <td width="50%" align="center">
-      <img src="docs/screenshots/dashboard-light.png" alt="Dashboard, light theme"><br>
+      <img src="https://raw.githubusercontent.com/schubydoo/clauster/main/docs/screenshots/dashboard-light.png" alt="Dashboard, light theme"><br>
       <sub><b>Dark / light</b> — theme toggle persists across reloads</sub>
     </td>
     <td width="50%" align="center">
-      <img src="docs/screenshots/new-project-clone.png" alt="Create or clone a project"><br>
+      <img src="https://raw.githubusercontent.com/schubydoo/clauster/main/docs/screenshots/new-project-clone.png" alt="Create or clone a project"><br>
       <sub><b>Create or clone</b> — SSRF-guarded, cloned code runs only on Start</sub>
     </td>
   </tr>
   <tr>
     <td width="50%" align="center">
-      <img src="docs/screenshots/login-dark.png" alt="Password login"><br>
+      <img src="https://raw.githubusercontent.com/schubydoo/clauster/main/docs/screenshots/login-dark.png" alt="Password login"><br>
       <sub><b>Password login</b> — for non-loopback / networked deploys</sub>
     </td>
     <td width="50%" align="center" valign="middle">
@@ -64,7 +64,7 @@ a project, start a bridge, and attach to it from `claude.ai/code` or the mobile
 
 Everything below is implemented and shipping. Items marked **(opt-in)** are gated
 behind a config flag and off by default — the flag is named inline so you can find
-it in [`clauster.yml.example`](clauster.yml.example).
+it in [`clauster.yml.example`](https://github.com/schubydoo/clauster/blob/main/clauster.yml.example).
 
 ### Projects & bridges
 
@@ -142,20 +142,33 @@ it; it isn't vendored).
 
 ## Docker
 
-Multi-arch images (`linux/amd64`, `linux/arm64`) are published to GHCR on each release:
+Multi-arch images (`linux/amd64`, `linux/arm64`) are published to GHCR on each release.
+The image binds `0.0.0.0`, so it **requires enforced auth** to start. First generate a
+password hash — this runs `clauster` *inside* the image, so you don't need it on the host:
+
+```sh
+docker run --rm -it ghcr.io/schubydoo/clauster:latest clauster hash-password
+```
+
+Copy the printed `$argon2id$…` hash, then start the server with auth enabled:
 
 ```sh
 docker run -d --name clauster \
   -p 7621:7621 \
   -e PUID=1000 -e PGID=1000 \
-  -e CLAUSTER_AUTH_PASSWORD_HASH="$(clauster hash-password)" \
+  -e CLAUSTER_AUTH_ENABLED=true \
+  -e CLAUSTER_AUTH_PASSWORD_REQUIRED=true \
+  -e 'CLAUSTER_AUTH_PASSWORD_HASH=$argon2id$v=19$...' \
   -v /path/to/config:/config \
   -v /path/to/projects:/projects \
   ghcr.io/schubydoo/clauster:latest
 ```
 
-- The image binds `0.0.0.0`, which **requires auth** — set `CLAUSTER_AUTH_PASSWORD_HASH`
-  (or put it in `/config/clauster.yml`) or the container exits on start.
+- The image binds `0.0.0.0`, so it won't start without **enforced** auth — set
+  `CLAUSTER_AUTH_ENABLED=true` **and** `CLAUSTER_AUTH_PASSWORD_REQUIRED=true` **and** a
+  `CLAUSTER_AUTH_PASSWORD_HASH` (or configure reverse-proxy trust in `/config/clauster.yml`),
+  or the container exits on start. Single-quote the hash env value — the argon2 hash
+  contains `$` that your shell would otherwise expand.
 - `/config` holds `clauster.yml` + state; `/projects` is your `projects_root`.
   `PUID`/`PGID` remap the runtime user to own bind-mounts.
 - `claude` is **not** baked in — tell Clauster where it is one of two ways: mount the
@@ -170,16 +183,17 @@ docker run -d --name clauster \
 ## Auth & networking
 
 Loopback (`127.0.0.1`) needs no auth. Binding to a non-loopback address is refused
-unless you enable one of: password login (`auth.password_required` + a hash from
-`clauster hash-password`), reverse-proxy trust (peer-IP allowlist + HMAC header), or
-an explicit `auth.allow_unauthenticated_network` opt-out for a trusted LAN. Sessions
+unless authentication is actually enforced — set `auth.enabled: true` (the master
+switch) together with either password login (`auth.password_required` + a hash from
+`clauster hash-password`) or reverse-proxy trust (peer-IP allowlist + HMAC header) —
+or, to opt out on a trusted LAN, `auth.allow_unauthenticated_network`. Sessions
 are signed cookies with server-side revocation ("log out everywhere"); WebSocket
 connections are authenticated before accept and origin-checked.
 
 ## Configuration
 
 All settings live in `clauster.yml` — see
-[`clauster.yml.example`](clauster.yml.example) for the full, commented schema. Any
+[`clauster.yml.example`](https://github.com/schubydoo/clauster/blob/main/clauster.yml.example) for the full, commented schema. Any
 scalar key is overridable by an environment variable of the form
 `CLAUSTER_<UPPER_SNAKE_PATH>`. The schema is additive-only — old configs always
 validate against newer versions.
@@ -188,6 +202,7 @@ validate against newer versions.
 | --- | --- | --- |
 | `host` / `port` | `127.0.0.1` / `7621` | bind address (non-loopback needs auth) |
 | `projects_root` | — | directory whose children become project cards |
+| `auth.enabled` | `false` | master auth switch — must be on for password / proxy auth to apply |
 | `auth.password_required` | `false` | require login (`clauster hash-password` for the hash) |
 | `claude.resume_recap` | `false` | recap the prior transcript into a restarted bridge |
 | `claude.resume_mode` | `standard` | `pty` = native true-resume on Restart (POSIX) |
@@ -234,4 +249,4 @@ and CI-gated on Linux; macOS / Windows are in the test matrix. Apache-2.0 licens
 
 ## License
 
-[Apache License 2.0](LICENSE).
+[Apache License 2.0](https://github.com/schubydoo/clauster/blob/main/LICENSE).

{clauster-0.2.0 → clauster-0.2.2}/clauster.yml.example

@@ -39,7 +39,8 @@ projects: {}
 #     allow_bypass_permissions: false
 
 auth:
-  enabled: false                   # turn on to require login / gate non-loopback
+  enabled: false                   # MASTER switch — must be true for password_required /
+                                   # reverse_proxy auth to actually be enforced
   password_required: false
   password_hash: null              # argon2id; generate via `clauster hash-password`
   cookie_secure: auto              # auto | always | never

{clauster-0.2.0 → clauster-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clauster"
-version = "0.2.0"
+version = "0.2.2"
 description = "Self-hosted web UI for spawning and managing Claude Code remote-control bridges on a remote host."
 readme = "README.md"
 requires-python = ">=3.11"

{clauster-0.2.0 → clauster-0.2.2}/src/clauster/__init__.py

@@ -1,3 +1,3 @@
 """Clauster — self-hosted dispatcher for Claude Code remote-control bridges."""
 
-__version__ = "0.2.0"  # x-release-please-version
+__version__ = "0.2.2"  # x-release-please-version

{clauster-0.2.0 → clauster-0.2.2}/src/clauster/config.py

@@ -122,6 +122,21 @@ class AuthConfig(BaseModel):
     )  # extra WS/CSRF origins (proxy domain)
 
 
+def _missing_enforced_auth(host: str, auth: AuthConfig) -> bool:
+    """Return True when binding ``host`` would NOT actually enforce authentication.
+
+    The runtime guard gates on ``auth.enabled``, so a non-loopback bind only enforces
+    auth when ``auth.enabled`` is set together with a method (``password_required`` or
+    ``reverse_proxy.enabled``). Loopback never needs auth. The explicit
+    ``allow_unauthenticated_network`` opt-out is intentionally left to callers (the
+    config validator permits it; ``ops._check_auth`` downgrades it to a warning) so
+    both use one shared definition of "enforced auth" without conflating the opt-out.
+    """
+    if host in _LOOPBACK_HOSTS:
+        return False
+    return not (auth.enabled and (auth.password_required or auth.reverse_proxy.enabled))
+
+
 class CloneConfig(BaseModel):
     """Project clone/create guards (spec §11 clone+trust chain).
 
@@ -215,17 +230,21 @@ class ClausterConfig(BaseModel):
 
     @model_validator(mode="after")
     def _loopback_or_authed(self) -> ClausterConfig:
-        # Non-loopback bind is only allowed once authentication can gate it.
-        if self.host not in _LOOPBACK_HOSTS:
-            a = self.auth
-            if not (
-                a.password_required or a.reverse_proxy.enabled or a.allow_unauthenticated_network
-            ):
-                raise ValueError(
-                    f"refusing non-loopback host={self.host!r} without auth. Set one of "
-                    "auth.password_required, auth.reverse_proxy.enabled, or (to opt out on a "
-                    "trusted LAN) auth.allow_unauthenticated_network."
-                )
+        # Non-loopback bind is only allowed once authentication will ACTUALLY gate it.
+        # The runtime guard enforces auth only when `auth.enabled` is true; with it false
+        # every request passes through unauthenticated, so `password_required` /
+        # `reverse_proxy.enabled` *without* `auth.enabled` is a silent open door — the
+        # operator sets a password, the validator accepted it, yet the dashboard is served
+        # to anyone. Require enforcement to be real here (fail closed) instead. Shared with
+        # ops._check_auth via _missing_enforced_auth so validation and diagnostics agree.
+        a = self.auth
+        if _missing_enforced_auth(self.host, a) and not a.allow_unauthenticated_network:
+            raise ValueError(
+                f"refusing non-loopback host={self.host!r} without enforced auth. Set "
+                "auth.enabled: true together with auth.password_required (+ a hash from "
+                "`clauster hash-password`) or auth.reverse_proxy.enabled — or, to opt out "
+                "on a trusted LAN, auth.allow_unauthenticated_network."
+            )
         # Fail closed: password auth required but no hash configured would lock everyone out
         # (or, worse, be skipped) — refuse to start with a clear message.
         if self.auth.password_required and not self.auth.password_hash:

{clauster-0.2.0 → clauster-0.2.2}/src/clauster/ops.py

@@ -19,7 +19,7 @@ from datetime import UTC, datetime
 from pathlib import Path, PurePosixPath
 
 from . import claude_cli
-from .config import ClausterConfig, load_config
+from .config import ClausterConfig, _missing_enforced_auth, load_config
 from .discovery import _load_trusted_paths, trust_state_for
 from .state import CURRENT_SCHEMA, StateStore
 
@@ -191,13 +191,12 @@ def _check_auth(config: ClausterConfig) -> Check:
     a = config.auth
     if a.password_required and not a.password_hash:
         return Check("auth", FAIL, "password_required but no password_hash set")
-    loopback = config.host in {"127.0.0.1", "::1", "localhost"}
-    if not loopback and not (
-        a.password_required or a.reverse_proxy.enabled or a.allow_unauthenticated_network
-    ):
-        return Check("auth", FAIL, f"non-loopback host {config.host} without any auth")
-    if not loopback and a.allow_unauthenticated_network:
-        return Check("auth", WARN, "bound non-loopback with auth explicitly disabled")
+    # Same "is auth actually enforced?" rule the config validator uses, so doctor never
+    # calls a config consistent that the validator would refuse to start.
+    if _missing_enforced_auth(config.host, a):
+        if a.allow_unauthenticated_network:
+            return Check("auth", WARN, "bound non-loopback with auth explicitly disabled")
+        return Check("auth", FAIL, f"non-loopback host {config.host} without enforced auth")
     return Check("auth", OK, "configuration consistent")
 
 

{clauster-0.2.0 → clauster-0.2.2}/tests/test_config.py

@@ -93,7 +93,10 @@ _HASH = (
 @pytest.mark.parametrize(
     "extra",
     [
-        "host: 0.0.0.0\nauth:\n  reverse_proxy:\n    enabled: true\n",
+        # reverse-proxy auth only counts when auth.enabled is set (it's the runtime gate).
+        "host: 0.0.0.0\nauth:\n  enabled: true\n  reverse_proxy:\n    enabled: true\n",
+        "host: 0.0.0.0\nauth:\n  enabled: true\n  password_required: true\n"
+        f"  password_hash: '{_HASH}'\n",
         "host: 0.0.0.0\nauth:\n  allow_unauthenticated_network: true\n",
     ],
 )
@@ -102,6 +105,21 @@ def test_non_loopback_allowed_with_auth(write_config, extra):
     assert config.host == "0.0.0.0"
 
 
+@pytest.mark.parametrize(
+    "extra",
+    [
+        # The footgun: a password (or proxy) is configured but auth.enabled is left at its
+        # false default, so the runtime guard would serve the dashboard unauthenticated.
+        # The validator must refuse rather than start a silently-open non-loopback bind.
+        f"host: 0.0.0.0\nauth:\n  password_required: true\n  password_hash: '{_HASH}'\n",
+        "host: 0.0.0.0\nauth:\n  reverse_proxy:\n    enabled: true\n",
+    ],
+)
+def test_non_loopback_rejected_when_auth_not_enabled(write_config, extra):
+    with pytest.raises(ValueError, match="without enforced auth"):
+        load_config(write_config(extra))
+
+
 def test_password_required_without_hash_fails_closed(write_config):
     cfg_path = write_config("auth:\n  enabled: true\n  password_required: true\n")
     with pytest.raises(ValueError, match="password_hash is empty"):

{clauster-0.2.0 → clauster-0.2.2}/uv.lock

@@ -179,7 +179,7 @@ wheels = [
 
 [[package]]
 name = "clauster"
-version = "0.1.0"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "argon2-cffi" },

clauster-0.2.0/.github/workflows/release-please.yml

@@ -1,60 +0,0 @@
-name: Release Please
-
-# Release Please reads Conventional Commits on main and opens a "release PR"
-# that bumps the version (src/clauster/__init__.py + pyproject.toml) and rewrites
-# CHANGELOG.md. Merging that PR tags the commit (e.g. `v0.2.0`), which fires
-# release.yml (`on: push: tags`).
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: read
-
-concurrency:
-  group: release-please-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  release-please:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    # GITHUB_TOKEN stays read-only: the App token (minted below) does all the
-    # writing, so the default token needs no write scope here.
-    permissions:
-      contents: read
-      pull-requests: read
-    steps:
-      # Mint a short-lived installation token for the Clauster release GitHub
-      # App so the release PR + version-bump commits are authored by the app's
-      # bot identity, NOT a human account. Crucially this is *not* the default
-      # GITHUB_TOKEN, so the tag pushed when the release PR merges still
-      # *triggers* release.yml (GITHUB_TOKEN-pushed tags don't — anti-recursion).
-      #
-      # Requires (set up once, manually):
-      #   - a GitHub App owned by the repo owner, installed on this repo, with
-      #     repo permissions Contents: R/W + Pull requests: R/W;
-      #   - secrets RELEASE_PLEASE_APP_ID (numeric App ID) and
-      #     RELEASE_PLEASE_APP_PRIVATE_KEY (the App's .pem private key).
-      # Until those exist this step 401s — merge this only after they're added.
-      # Supersedes the old RELEASE_PLEASE_TOKEN PAT (which attributed PRs to a
-      # real user); that secret can be deleted once this is live.
-      - name: Mint GitHub App token
-        id: app-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-        with:
-          app-id: ${{ secrets.RELEASE_PLEASE_APP_ID }}
-          private-key: ${{ secrets.RELEASE_PLEASE_APP_PRIVATE_KEY }}
-          # Scope the minted token to exactly what release-please needs, rather
-          # than inheriting the installation's full permission set (zizmor
-          # least-privilege). Add permission-issues: write only if you enable
-          # release-please's label-on-issue features.
-          permission-contents: write
-          permission-pull-requests: write
-
-      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-          config-file: release-please-config.json
-          manifest-file: .release-please-manifest.json

clauster-0.2.0/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.2.0"
-}