zfs-unlock 0.1.0__tar.gz

zfs_unlock-0.1.0/.envrc

@@ -0,0 +1 @@
+source .venv/bin/activate

zfs_unlock-0.1.0/.github/release-drafter.yml

@@ -0,0 +1,5 @@
+---
+template: |
+  ## What’s Changed
+
+  $CHANGES

zfs_unlock-0.1.0/.github/renovate.json

@@ -0,0 +1,35 @@
+{
+    "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+    "rebaseWhen": "behind-base-branch",
+    "dependencyDashboard": true,
+    "labels": [
+        "dependencies",
+        "no-stale"
+    ],
+    "commitMessagePrefix": "⬆️",
+    "commitMessageTopic": "{{depName}}",
+    "prBodyDefinitions": {
+        "Release": "yes"
+    },
+    "packageRules": [
+        {
+            "matchManagers": [
+                "github-actions"
+            ],
+            "addLabels": [
+                "github_actions"
+            ],
+            "rangeStrategy": "pin"
+        },
+        {
+            "matchManagers": [
+                "github-actions"
+            ],
+            "matchUpdateTypes": [
+                "minor",
+                "patch"
+            ],
+            "automerge": true
+        }
+    ]
+}

zfs_unlock-0.1.0/.github/workflows/pytest.yml

@@ -0,0 +1,31 @@
+---
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run mypy zfs_unlock.py
+      - name: Test
+        run: uv run pytest --cov=zfs_unlock --cov-report=term-missing

zfs_unlock-0.1.0/.github/workflows/release-drafter.yml

@@ -0,0 +1,15 @@
+---
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  update_release_draft:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

zfs_unlock-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+---
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ github.repository }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build
+        run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

zfs_unlock-0.1.0/.github/workflows/toc.yaml

@@ -0,0 +1,16 @@
+---
+name: TOC Generator
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  generateTOC:
+    name: TOC Generator
+    runs-on: ubuntu-latest
+    steps:
+      - uses: technote-space/toc-generator@v4
+        with:
+          TOC_TITLE: ""

zfs_unlock-0.1.0/.github/workflows/update-readme.yml

@@ -0,0 +1,48 @@
+---
+name: Update README.md
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  update_readme:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Run markdown-code-runner
+        run: uvx --with . markdown-code-runner README.md
+
+      - name: Commit updated README.md
+        id: commit
+        run: |
+          git add README.md
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          if git diff --quiet && git diff --staged --quiet; then
+            echo "No changes in README.md, skipping commit."
+            echo "commit_status=skipped" >> $GITHUB_ENV
+          else
+            git commit -m "Update README.md"
+            echo "commit_status=committed" >> $GITHUB_ENV
+          fi
+
+      - name: Push changes
+        if: env.commit_status == 'committed'
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ github.head_ref }}

zfs_unlock-0.1.0/.gitignore

@@ -0,0 +1,166 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# Pyre type checker
+.pyre/
+
+# hatch-vcs generated version file
+_version.py
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

zfs_unlock-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+---
+ci:
+    skip: [mypy, pytest]
+
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v5.0.0
+      hooks:
+          - id: trailing-whitespace
+          - id: end-of-file-fixer
+          - id: check-yaml
+          - id: check-added-large-files
+    - repo: https://github.com/codespell-project/codespell
+      rev: v2.4.1
+      hooks:
+          - id: codespell
+    - repo: https://github.com/adrienverge/yamllint
+      rev: v1.37.1
+      hooks:
+          - id: yamllint
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      rev: v0.8.4
+      hooks:
+          - id: ruff
+            args: [--fix]
+          - id: ruff-format
+    - repo: local
+      hooks:
+          - id: mypy
+            name: mypy
+            entry: uv run mypy
+            language: system
+            types: [python]
+            pass_filenames: false
+            args: [zfs_unlock.py]
+          - id: pytest
+            name: pytest
+            entry: uv run pytest
+            language: system
+            types: [python]
+            pass_filenames: false

zfs_unlock-0.1.0/.yamllint

@@ -0,0 +1,7 @@
+---
+extends: default
+rules:
+  truthy:
+    allowed-values: ["true", "false", "on"]
+  line-length:
+    max: 120

zfs_unlock-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bas Nijholt
+
+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.

zfs_unlock-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: zfs-unlock
+Version: 0.1.0
+Summary: Unlock encrypted OpenZFS datasets over a restricted SSH receiver
+Project-URL: Homepage, https://github.com/basnijholt/zfs-unlock
+Project-URL: Repository, https://github.com/basnijholt/zfs-unlock
+Project-URL: Issues, https://github.com/basnijholt/zfs-unlock/issues
+Author-email: Bas Nijholt <bas@nijho.lt>
+License: MIT
+License-File: LICENSE
+Keywords: encryption,nas,nixos,openzfs,unlock,zfs
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Description-Content-Type: text/markdown
+
+# ZFS Unlock
+
+[![PyPI](https://img.shields.io/pypi/v/zfs-unlock)](https://pypi.org/project/zfs-unlock/)
+[![Python](https://img.shields.io/pypi/pyversions/zfs-unlock)](https://pypi.org/project/zfs-unlock/)
+[![Tests](https://github.com/basnijholt/zfs-unlock/actions/workflows/pytest.yml/badge.svg)](https://github.com/basnijholt/zfs-unlock/actions/workflows/pytest.yml)
+[![License](https://img.shields.io/github/license/basnijholt/zfs-unlock)](LICENSE)
+
+Unlock encrypted OpenZFS datasets over a restricted SSH receiver.
+
+## Why?
+
+This is the NixOS/OpenZFS counterpart to
+[`truenas-unlock`](https://github.com/basnijholt/truenas-unlock).
+
+ZFS native encryption is useful, but:
+
+1. **Storing keys on the NAS defeats the purpose**—if it's stolen, the thief has both the encrypted data and the keys
+2. **Manual unlocking is tedious**—after every reboot, you need to manually decrypt each dataset
+
+This tool solves both problems with the same **"poor-man's second-factor"** setup as `truenas-unlock`:
+
+1. Run `zfs-unlock` on a **separate device** (Raspberry Pi, home server, etc.)
+2. Store encryption passphrases **only on that device**
+3. Datasets auto-unlock when both devices are on the network
+4. If the NAS is stolen, data remains encrypted and inaccessible
+
+Unlike a plain root SSH key, the NAS-side path is intentionally narrow:
+
+- a dedicated `zfs-unlock` SSH user
+- an SSH key restricted with `restrict`, `from=...`, and `command=...`
+- sudo permission only for a root-owned receiver wrapper
+- a NAS-side dataset allowlist
+- a receiver parser that only accepts `status`, `unlock`, and `lock`
+
+Think of it as a hardware security key for your storage—hidden somewhere in your house, it automatically unlocks your datasets whenever your NAS boots. No manual intervention required.
+
+## Table of Contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Install](#install)
+- [Setup](#setup)
+- [Usage](#usage)
+- [CLI](#cli)
+- [Running as a Service](#running-as-a-service)
+- [Development](#development)
+- [Credits](#credits)
+- [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install zfs-unlock
+
+# With pip
+pip install zfs-unlock
+```
+
+## Setup
+
+Create `~/.config/zfs-unlock/config.yaml` on the off-box unlock device:
+
+```yaml
+host: nas.local
+user: zfs-unlock
+identity_file: ~/.ssh/zfs-unlock-nas
+
+# secrets: auto  # auto (default) | files | inline
+
+datasets:
+  tank/syncthing: ~/.secrets/syncthing-key
+  tank/photos: my-literal-passphrase
+```
+
+The `secrets` mode controls how values are interpreted:
+- **auto** (default): if file exists, read from it; otherwise use as literal
+- **files**: always treat values as file paths
+- **inline**: always treat values as literal secrets
+
+On the NAS, install a forced-command receiver. A NixOS setup can look like this:
+
+```nix
+{ pkgs, ... }:
+
+let
+  zfsUnlock = pkgs.writeShellScriptBin "zfs-unlock" ''
+    exec ${pkgs.uv}/bin/uv tool run zfs-unlock "$@"
+  '';
+
+  receiver = pkgs.writeShellScript "zfs-unlock-receiver" ''
+    exec ${zfsUnlock}/bin/zfs-unlock receiver \
+      --allow-file /etc/zfs-unlock/allowed-datasets "$@"
+  '';
+
+  sshWrapper = pkgs.writeShellScript "zfs-unlock-ssh-wrapper" ''
+    set -eu
+    exec ${pkgs.sudo}/bin/sudo -n ${receiver} "$SSH_ORIGINAL_COMMAND"
+  '';
+in
+{
+  users.groups.zfs-unlock = {};
+
+  users.users.zfs-unlock = {
+    isSystemUser = true;
+    group = "zfs-unlock";
+    home = "/var/lib/zfs-unlock";
+    createHome = true;
+    openssh.authorizedKeys.keys = [
+      ''restrict,from="192.168.1.50",command="${sshWrapper}" ssh-ed25519 AAAA... unlock-device''
+    ];
+  };
+
+  security.sudo.extraRules = [
+    {
+      users = [ "zfs-unlock" ];
+      commands = [
+        {
+          command = "${receiver}";
+          options = [ "NOPASSWD" ];
+        }
+      ];
+    }
+  ];
+
+  environment.etc."zfs-unlock/allowed-datasets".text = ''
+    tank/syncthing
+    tank/photos
+  '';
+}
+```
+
+The wrapper captures `SSH_ORIGINAL_COMMAND` before `sudo` and passes it as one argument to the root receiver. The receiver still checks the requested dataset against `/etc/zfs-unlock/allowed-datasets`.
+
+## Usage
+
+```bash
+# Run once
+zfs-unlock
+
+# Run as daemon
+# (Checks every 1s if NAS is unreachable, otherwise every 30s)
+zfs-unlock --daemon
+
+# Custom interval (for the "relaxed" state)
+zfs-unlock --daemon --interval 60
+
+# Dry run
+zfs-unlock --dry-run
+```
+
+## CLI
+
+```bash
+zfs-unlock --help
+```
+
+<!-- CODE:BASH:START -->
+<!-- export NO_COLOR=1 -->
+<!-- export TERM=dumb -->
+<!-- export TERMINAL_WIDTH=90 -->
+<!-- echo '```bash' -->
+<!-- zfs-unlock --help -->
+<!-- echo '```' -->
+<!-- CODE:END -->
+
+<!-- OUTPUT:START -->
+<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
+```bash
+
+ Usage: zfs-unlock [OPTIONS] COMMAND [ARGS]...
+
+ Unlock OpenZFS datasets over a restricted SSH receiver
+
+╭─ Options ────────────────────────────────────────────────────────────────────╮
+│ --config    -c      PATH     Config file path                                │
+│ --dry-run   -n               Show what would be done                         │
+│ --daemon    -d               Run continuously                                │
+│ --interval  -i      INTEGER  Seconds between checks (1s if unreachable)      │
+│                              [default: 30]                                   │
+│ --dataset   -D      TEXT     Filter by dataset path                          │
+│ --version   -v               Show version and exit                           │
+│ --help      -h               Show this message and exit.                     │
+╰──────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ───────────────────────────────────────────────────────────────────╮
+│ lock      Lock configured datasets.                                          │
+│ status    Show lock status of configured datasets.                           │
+│ receiver  Run the restricted NAS-side receiver.                              │
+│ service   Manage system service                                              │
+╰──────────────────────────────────────────────────────────────────────────────╯
+
+```
+
+<!-- OUTPUT:END -->
+
+## Running as a Service
+
+Requires [uv](https://docs.astral.sh/uv/) to be installed. Auto-detects Linux (systemd) or macOS (launchd):
+
+```bash
+# Install and start
+zfs-unlock service install
+
+# Check status
+zfs-unlock service status
+
+# View logs (follows by default)
+zfs-unlock service logs
+
+# Uninstall
+zfs-unlock service uninstall
+```
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/basnijholt/zfs-unlock
+cd zfs-unlock
+uv sync --dev
+
+# Run tests
+uv run pytest
+
+# Run lints
+uv run ruff check .
+uv run mypy zfs_unlock.py
+```
+
+## Credits
+
+Based on [`truenas-unlock`](https://github.com/basnijholt/truenas-unlock).
+
+## License
+
+MIT