hirsch-securefido 1.0.0__tar.gz

hirsch_securefido-1.0.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+
+# macOS
+.DS_Store
+
+# Editors
+.idea/
+.vscode/
+*.swp

hirsch_securefido-1.0.0/Formula/hirsch-securefido.rb

@@ -0,0 +1,82 @@
+# typed: false
+# frozen_string_literal: true
+
+# Homebrew formula for the Hirsch SecureFIDO device-configuration CLI.
+#
+# Regenerate the `resource` blocks after a dependency bump with:
+#     ./scripts/brew_release.sh <version>
+#
+# The top-level `sha256` is a placeholder until the sdist is published to
+# PyPI; `scripts/brew_release.sh` fills in the real digest. See HOMEBREW.md.
+class HirschSecurefido < Formula
+  include Language::Python::Virtualenv
+
+  desc "Device configuration CLI for Hirsch SecureKey FIDO2 authenticators"
+  homepage "https://github.com/hirschsecure/hirsch-securefido"
+  url "https://files.pythonhosted.org/packages/source/h/hirsch-securefido/hirsch_securefido-1.0.0.tar.gz"
+  sha256 "REPLACE_WITH_SDIST_SHA256"
+  license "BSD-3-Clause"
+
+  depends_on "python@3.12"
+
+  # cryptography ships prebuilt wheels, but Homebrew builds from source, so the
+  # Rust toolchain is required to compile its extension modules.
+  depends_on "rust" => :build
+
+  resource "cffi" do
+    url "https://files.pythonhosted.org/packages/9e/ef/008a1939e372c06329a3fce4279c02f328488f3526744906eeec3da7ad5f/cffi-2.1.1.tar.gz"
+    sha256 "dd31f52ea1086513bb9df30f8fcee9b8918323ae067a3d5b78bc826a000712be"
+  end
+
+  resource "pycparser" do
+    url "https://files.pythonhosted.org/packages/1b/7d/92392ff7815c21062bea51aa7b87d45576f649f16458d78b7cf94b9ab2e6/pycparser-3.0.tar.gz"
+    sha256 "600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29"
+  end
+
+  resource "cryptography" do
+    url "https://files.pythonhosted.org/packages/bb/ad/5d6702db60b1e40b41ef513b6967ff5848f307d50f8449baf1634f5908f1/cryptography-50.0.1.tar.gz"
+    sha256 "5dd9bda1c12b4162f6ff568eeb5e0ff956c28d14406e875cfe8a63a2d414ff20"
+  end
+
+  resource "fido2" do
+    url "https://files.pythonhosted.org/packages/ba/ea/6f08c354b7aeb8019249d46a86c2153f8218499cced4d21bf16b6d49fc16/fido2-2.2.1.tar.gz"
+    sha256 "85787428a94c3f8eaf72f0ff30afba983b559a1b1b795c93318c81b4ad4062c4"
+  end
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  def caveats
+    <<~EOS
+      hirsch-securefido talks to FIDO2 authenticators over USB HID.
+      No sudo is required on macOS: HID access is granted to the console user.
+
+      Verify your setup with:
+        hirsch-securefido list
+        hirsch-securefido info
+
+      NFC / smart-card readers need the optional pyscard extra:
+        $(brew --prefix)/opt/hirsch-securefido/libexec/bin/pip install pyscard
+    EOS
+  end
+
+  test do
+    # Version reporting must work with no hardware attached.
+    assert_match version.to_s, shell_output("#{bin}/hirsch-securefido --version")
+
+    # Help must advertise exactly the four device-configuration commands.
+    help = shell_output("#{bin}/hirsch-securefido --help")
+    ["info", "set-pin", "change-pin", "reset"].each do |cmd|
+      assert_match cmd, help
+    end
+
+    # With no authenticator present the tool must exit 2 (EXIT_NO_DEVICE)
+    # rather than crash with a traceback.
+    output = shell_output("#{bin}/hirsch-securefido info 2>&1", 2)
+    assert_match "No Hirsch FIDO2 token found", output
+
+    # The library must import cleanly inside the virtualenv.
+    system libexec/"bin/python", "-c", "import hirsch_securefido"
+  end
+end

hirsch_securefido-1.0.0/HOMEBREW.md

@@ -0,0 +1,207 @@
+# Publishing to Homebrew
+
+How to get `brew install hirsch-securefido` working on macOS.
+
+## The ordering constraint
+
+Homebrew does not host code. The formula points at a **PyPI sdist** and builds
+from it, so the order is fixed:
+
+```
+1. publish to PyPI   ->   2. get the sdist sha256   ->   3. update the formula   ->   4. push the tap
+```
+
+Step 3 cannot happen first. Until the version exists on PyPI there is nothing
+to checksum, which is why `Formula/hirsch-securefido.rb` currently carries
+`REPLACE_WITH_SDIST_SHA256`.
+
+## Which distribution channel?
+
+| | Formula (`brew install`) | Cask (`brew install --cask`) |
+| --- | --- | --- |
+| For | CLI tools built from source | prebuilt `.app` bundles, binaries |
+| Ours | **yes** | no |
+
+This is a command-line tool, so it is a **formula**. A cask would only apply if
+you later ship a `.app`, which would additionally need codesigning and
+notarization.
+
+## Which tap?
+
+**Your own tap** (`hirschsecure/homebrew-tap`) is the right choice here:
+
+- You control releases; no third-party review queue.
+- homebrew-core requires notability (roughly 30+ GitHub stars, 30+ forks, or
+  equivalent usage) and rejects vendor-specific hardware tools that only work
+  with one company's device. This tool is gated to Hirsch VID `04E6`, so it
+  would very likely be declined.
+
+Users then run:
+
+```bash
+brew tap hirschsecure/tap
+brew install hirsch-securefido
+```
+
+`brew tap hirschsecure/tap` resolves to `github.com/hirschsecure/homebrew-tap`.
+The `homebrew-` prefix on the repo name is required; the tap name drops it.
+
+---
+
+## Step 1 - Publish to PyPI
+
+One-time: register the project name and configure Trusted Publishing at
+<https://pypi.org/manage/account/publishing/>
+
+| Field | Value |
+| --- | --- |
+| PyPI project | `hirsch-securefido` |
+| Owner | `hirschsecure` |
+| Repository | `hirsch-securefido` |
+| Workflow | `publish.yml` |
+| Environment | `pypi` |
+
+Then release:
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+The `Publish` workflow verifies the tag matches `pyproject.toml`, builds, and
+uploads with no stored API token. Confirm it worked:
+
+```bash
+pip download --no-deps --no-binary :all: hirsch-securefido==1.0.0
+```
+
+### Manual alternative
+
+```bash
+python -m build
+twine upload --repository testpypi dist/*   # rehearse
+twine upload dist/*
+```
+
+## Step 2 - Create the tap repository
+
+Once, on GitHub: create a **public** repo named `homebrew-tap` under the
+`hirschsecure` org.
+
+```bash
+git clone https://github.com/hirschsecure/homebrew-tap
+cd homebrew-tap
+mkdir -p Formula
+```
+
+The `Formula/` subdirectory name matters; Homebrew looks there.
+
+## Step 3 - Update the formula for the release
+
+On macOS, from this repository:
+
+```bash
+./scripts/brew_release.sh 1.0.0
+```
+
+That script:
+
+1. confirms `1.0.0` is actually on PyPI, and stops if not
+2. rewrites the formula's `url` and `sha256` from the real sdist
+3. regenerates the Python `resource` blocks via `brew update-python-resources`
+4. runs `ruby -c` and `brew style`
+
+It edits **only** the formula's own url/sha256; the four vendored resource
+digests are left untouched.
+
+## Step 4 - Validate locally before publishing
+
+Do not skip this. It is the first time the formula is genuinely exercised.
+
+```bash
+brew install --build-from-source Formula/hirsch-securefido.rb
+brew test hirsch-securefido
+brew audit --strict --new hirsch-securefido
+```
+
+- `install` proves the virtualenv builds and every resource resolves. Expect a
+  few minutes: `cryptography` compiles Rust extensions from source.
+- `test` runs the formula's test block: `--version`, the four commands in
+  `--help`, and the exit-2 no-device contract.
+- `audit --strict --new` applies the rules a new formula must satisfy.
+
+Then confirm it behaves with hardware attached:
+
+```bash
+hirsch-securefido            # interactive menu
+hirsch-securefido info       # must work WITHOUT sudo
+```
+
+## Step 5 - Push the tap
+
+```bash
+cp Formula/hirsch-securefido.rb ../homebrew-tap/Formula/
+cd ../homebrew-tap
+git add Formula/hirsch-securefido.rb
+git commit -m "hirsch-securefido 1.0.0"
+git push
+```
+
+Verify as a user would, from a clean state:
+
+```bash
+brew untap hirschsecure/tap 2>/dev/null || true
+brew tap hirschsecure/tap
+brew install hirsch-securefido
+hirsch-securefido --version
+```
+
+## Subsequent releases
+
+```bash
+# 1. bump the version in pyproject.toml AND src/hirsch_securefido/__init__.py
+#    (tests/test_packaging.py fails if they disagree)
+git tag v1.1.0 && git push origin v1.1.0     # publishes to PyPI
+
+# 2. refresh and validate the formula
+./scripts/brew_release.sh 1.1.0
+brew install --build-from-source Formula/hirsch-securefido.rb
+brew test hirsch-securefido
+
+# 3. ship it
+cp Formula/hirsch-securefido.rb ../homebrew-tap/Formula/
+cd ../homebrew-tap && git commit -am "hirsch-securefido 1.1.0" && git push
+```
+
+Users upgrade with `brew update && brew upgrade hirsch-securefido`.
+
+## Troubleshooting
+
+**`SHA256 mismatch`** - the formula's checksum does not match what PyPI served.
+Re-run `./scripts/brew_release.sh <version>`. Never edit a digest by hand.
+
+**`Could not find a version that satisfies the requirement`** - a transitive
+dependency lacks a `resource` block. Re-run `brew update-python-resources`.
+
+**`cryptography` fails to build** - the Rust toolchain is missing. The formula
+declares `depends_on "rust" => :build`; confirm `brew install rust` succeeds.
+
+**`Error: Formula is not in the tap`** - the file must be at
+`Formula/hirsch-securefido.rb`, and the class name `HirschSecurefido` must match
+the filename. `tests/test_formula.py` checks that pairing.
+
+**`No such keg`** on `brew test` - install before testing.
+
+## What is verified, and what is not
+
+Automated in CI (`.github/workflows/ci.yml`, `formula` job on macOS):
+`ruby -c` parses the formula, and `brew style` audits it.
+
+Also checked offline by `tests/test_formula.py`: block balance, required
+fields, audit-sensitive `desc` style, version agreement, full-length resource
+digests, and that the test block asserts real behavior. Resource URLs are
+confirmed reachable on PyPI over the network.
+
+**Not verified here**, because this repo has no macOS host, no Ruby, and no
+Hirsch key: `brew install`, `brew test`, `brew audit`, and every USB HID path.
+Step 4 is the first time those run. Treat it as required, not optional.

hirsch_securefido-1.0.0/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, Hirsch Secure, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

hirsch_securefido-1.0.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: hirsch-securefido
+Version: 1.0.0
+Summary: Device configuration for Hirsch SecureKey FIDO2 authenticators: device info, set PIN, change PIN, factory reset.
+Project-URL: Homepage, https://github.com/hirschsecure/hirsch-securefido
+Project-URL: Repository, https://github.com/hirschsecure/hirsch-securefido
+Project-URL: Issues, https://github.com/hirschsecure/hirsch-securefido/issues
+Author: Hirsch Secure, Inc.
+License: Copyright (c) 2026, Hirsch Secure, Inc.
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Keywords: ctap,fido2,hirsch,macos,passkey,security-key,webauthn
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Requires-Dist: fido2>=1.1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: pcsc
+Requires-Dist: pyscard>=2.0.0; extra == 'pcsc'
+Description-Content-Type: text/markdown
+
+# Hirsch SecureFIDO Device Config
+
+Command-line device configuration for Hirsch SecureKey / SecureKey GOV FIDO2
+authenticators on macOS.
+
+This is the **device configuration subset** of the Windows
+*Hirsch SecureFIDO Cred Manager*. It provides exactly four operations:
+
+| Command | Description | Origin |
+| --- | --- | --- |
+| `info` | Read authenticator info: AAGUID, versions, options, limits, PIN retries | ported from the Windows app |
+| `set-pin` | Set the initial PIN on a factory-fresh token | new |
+| `change-pin` | Change an existing PIN | new |
+| `reset` | Factory reset: erase all credentials and clear the PIN | new |
+
+Only the device-info view existed in the Windows original. It read
+authenticator info and rendered the AAGUID, versions, options, and limits;
+that logic, including the option labels and COSE algorithm names, is carried
+over here. The Windows app could *report* on the PIN (retry count, whether one
+was set) and could surface PIN errors, but it had no way to set, change, or
+clear one: it only ever called `getPinToken` to authenticate credential
+management. Set PIN, Change PIN, and Factory Reset are therefore newly
+implemented against CTAP `authenticatorClientPIN` and `authenticatorReset`.
+
+Credential enumeration and deletion, which were the Windows app's main
+purpose, are intentionally **not** included.
+
+## Install
+
+### Homebrew
+
+```bash
+brew tap hirschsecure/tap
+brew install hirsch-securefido
+```
+
+### PyPI
+
+```bash
+pip install hirsch-securefido
+
+# with NFC / CCID reader support
+pip install "hirsch-securefido[pcsc]"
+```
+
+## Usage
+
+Run it with no arguments for an interactive menu:
+
+```
+$ hirsch-securefido
+
+  Hirsch SecureFIDO Device Config  v1.0.0
+  --------------------------------------------------------
+  Hirsch SecureKey  USB HID (VID 04E6)  PIN set, 8 attempt(s) left
+  --------------------------------------------------------
+
+    1  Device information
+    2  Set PIN
+    3  Change PIN
+    4  Factory reset
+    r  Refresh device status
+    q  Quit
+
+  Select an option:
+```
+
+The header shows live device status and refreshes after every action. The
+menu appears **only** on an interactive terminal: with a piped stdin or
+redirected stdout the tool prints help and exits, so scripts never block on a
+prompt.
+
+Every operation is also available directly:
+
+```bash
+hirsch-securefido info              # human-readable device report
+hirsch-securefido info --json       # machine-readable, for MDM tooling
+hirsch-securefido list              # enumerate connected authenticators
+
+hirsch-securefido set-pin           # prompts for a new PIN, twice
+hirsch-securefido change-pin        # prompts for current then new PIN
+hirsch-securefido reset             # requires typing RESET, then a touch
+```
+
+By default only Hirsch authenticators (USB Vendor ID `04E6`) are accepted.
+Pass `--any-vendor` to work with other FIDO2 keys.
+
+### Unattended use
+
+PINs may be supplied by environment variable for provisioning scripts:
+
+```bash
+HIRSCH_PIN=oldpin HIRSCH_NEW_PIN=newpin hirsch-securefido change-pin
+hirsch-securefido reset --yes
+```
+
+PINs are also read from stdin when it is not a TTY:
+
+```bash
+echo "123456" | hirsch-securefido set-pin
+```
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | General device error |
+| `2` | No authenticator found |
+| `3` | PIN rejected or blocked |
+| `4` | Operation unsupported by the token |
+| `130` | Cancelled by the user |
+
+## Factory reset
+
+CTAP requires a factory reset to arrive within a few seconds of the token
+powering up, confirmed by a physical touch. The `reset` command therefore
+prompts you to unplug and re-insert the token first. If you see
+"a factory reset must be started within a few seconds", re-insert the key and
+run the command again promptly.
+
+A reset destroys every passkey on the device and clears the PIN. You will lose
+access to any account that relies on this key as its only factor.
+
+## macOS notes
+
+The Windows original auto-elevated to Administrator, because non-elevated
+Windows processes cannot open FIDO HID authenticators. macOS grants HID access
+to the console user, so **no `sudo` is required**. The Windows-only
+`winscard.dll` / `cfgmgr32.dll` hardware gate and disconnect watchdog have been
+replaced by a direct USB Vendor ID check on the CTAP HID descriptor.
+
+`pyscard` is optional. Install the `pcsc` extra only if you need NFC or
+smart-card readers; it requires the PCSC-Lite build toolchain.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+The test suite runs entirely against software authenticators, so no hardware is
+needed. It has two layers:
+
+- `tests/test_device.py`, `tests/test_cli.py` stub out `fido2` to test error
+  handling and CLI behavior in isolation.
+- `tests/test_integration.py` runs the **real** python-fido2 stack (CBOR, ECDH
+  key agreement, AES-CBC PIN encryption, HMAC `pinUvAuthParam`) against the
+  virtual authenticator in `tests/virtual_authenticator.py`, then asserts on
+  the resulting device state.
+
+To confirm the suite actually detects bugs rather than passing vacuously:
+
+```bash
+python scripts/mutation_check.py
+```
+
+This injects plausible defects (swapped PIN arguments, a skipped guard, a reset
+that never fires) and requires the suite to fail on each one.
+
+### What software cannot verify
+
+USB HID transport, the CTAP reset power-up window, and the physical touch
+confirmation have no software equivalent. `brew install` likewise needs macOS.
+These are covered by the manual hardware checklist in
+[PUBLISHING.md](PUBLISHING.md).
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

hirsch_securefido-1.0.0/PUBLISHING.md

@@ -0,0 +1,118 @@
+# Publishing
+
+Release checklist for `hirsch-securefido`.
+
+## 1. Pre-flight
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests
+pytest -q
+python scripts/mutation_check.py    # suite must detect all injected bugs
+python -m build
+twine check dist/*
+```
+
+Confirm the version in `pyproject.toml` and `src/hirsch_securefido/__init__.py`
+match, and that `CHANGELOG` / README reflect the release. `tests/test_packaging.py`
+and `tests/test_formula.py` enforce that agreement automatically.
+
+## 2. PyPI
+
+### Automated (recommended)
+
+The `Publish` workflow uses PyPI **Trusted Publishing** (OIDC), so no API token
+is stored in the repository.
+
+One-time setup at
+<https://pypi.org/manage/project/hirsch-securefido/settings/publishing/>:
+
+| Field | Value |
+| --- | --- |
+| Owner | `hirschsecure` |
+| Repository | `hirsch-securefido` |
+| Workflow | `publish.yml` |
+| Environment | `pypi` |
+
+Then release by tagging:
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+The workflow refuses to publish if the tag does not match the packaged version.
+
+### Manual
+
+```bash
+python -m build
+twine upload --repository testpypi dist/*   # rehearse first
+twine upload dist/*
+```
+
+Verify the published artifact installs cleanly:
+
+```bash
+python -m venv /tmp/verify && /tmp/verify/bin/pip install hirsch-securefido
+/tmp/verify/bin/hirsch-securefido --version
+```
+
+## 3. Homebrew
+
+See **[HOMEBREW.md](HOMEBREW.md)** for the full walkthrough: tap setup,
+formula-vs-cask, local validation, and troubleshooting.
+
+Short version, after the PyPI release is live:
+
+```bash
+./scripts/brew_release.sh 1.0.0          # rewrites url + sha256, refreshes resources
+brew install --build-from-source Formula/hirsch-securefido.rb
+brew test hirsch-securefido
+brew audit --strict --new hirsch-securefido
+```
+
+Then publish to the tap:
+
+```bash
+cp Formula/hirsch-securefido.rb ../homebrew-tap/Formula/
+cd ../homebrew-tap && git commit -am "hirsch-securefido 1.0.0" && git push
+```
+
+Users install with:
+
+```bash
+brew tap hirschsecure/tap
+brew install hirsch-securefido
+```
+
+## 4. Post-release
+
+```bash
+brew uninstall hirsch-securefido && brew install hirschsecure/tap/hirsch-securefido
+hirsch-securefido info    # with a real Hirsch key attached
+```
+
+## Manual hardware verification
+
+Everything below is **outside** what the automated suite can reach. The tests
+use a virtual authenticator that speaks real CTAP2 CBOR, so protocol logic is
+covered, but USB HID transport, the reset power-up window, and the physical
+touch have no software equivalent.
+
+Run this once per release on macOS with a real Hirsch SecureKey:
+
+- [ ] `hirsch-securefido list` shows the key over USB HID
+- [ ] `hirsch-securefido info` reports the true AAGUID and firmware version
+- [ ] `info` runs **without `sudo`** (the core macOS port claim)
+- [ ] `set-pin` on a factory-fresh token
+- [ ] `change-pin` with the correct current PIN
+- [ ] `change-pin` with a wrong PIN decrements the retry counter shown by `info`
+- [ ] `reset` refused when run outside the power-up window
+- [ ] `reset` succeeds when the token is re-inserted, and the touch prompt appears
+- [ ] `reset` cancelled by declining the touch, leaving credentials intact
+- [ ] After a successful `reset`, `info` reports `PIN Set: No`
+- [ ] NFC path with `pip install pyscard` and a card on a reader, if in scope
+
+Record the macOS version, the key's firmware version, and the fido2 version
+used, so a regression can be attributed later.