Update Documentation

2026-08-11 12:18:21 -05:00
parent 802474fe6d
commit f85f1a2c9f
4 changed files with 157 additions and 144 deletions
@@ -30,7 +30,7 @@ The workflow is:
 Please note: GitHub `main` and Gitea `staging-dev` may contain new features and
 code not yet in `stable`, and that code may not be fully tested.
-Moreover, Sovran_SystemsOS has been improved with the help of AI. We have used Copilot and Arean.Ai to work through significant coding challenges and troubleshooting hurdles. We will continue to use AI to help keep Sovran_SystemsOS stable and maintained.
+Moreover, Sovran_SystemsOS has been improved with the help of AI. We have used Copilot and Arena.ai to work through significant coding challenges and troubleshooting hurdles. We will continue to use AI to help keep Sovran_SystemsOS stable and maintained.
 ## How Can I Contribute?
@@ -92,6 +92,13 @@ git push origin feature/your-feature-name
 - **Do not push directly to `main`.** Always use a feature branch and open a PR.
 - **Be patient.** PRs will be reviewed as soon as possible.
 ## Security-Sensitive Changes
 - Report vulnerabilities privately as described in [`SECURITY.md`](SECURITY.md).
 - Pin upstream revisions and hashes; do not use floating source references.
 - Update [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) when importing code.
 - Add regression tests and describe any threat-model change in the pull request.
 ## Code Style
 - Follow the existing patterns in the codebase
@@ -507,14 +507,13 @@ setup, supported hardware, and Royal Membership.
 ## For developers
-Sovran_SystemsOS combines the reproducibility of [NixOS](https://nixos.org),
+Sovran_SystemsOS combines [NixOS](https://nixos.org), an in-repository
-the Bitcoin service modules of
+Bitcoin and Lightning stack, desktop packages from
 [nix-bitcoin](https://github.com/fort-nix/nix-bitcoin), the desktop Bitcoin
 packages provided by
 [btc-clients-nix](https://github.com/emmanuelrosa/btc-clients-nix), and the
-Sovran Hub into a complete Bitcoin operating system. The operating system
+Sovran Hub. The Bitcoin modules under `modules/bitcoin/` were adapted from
-configuration, installer, Hub, desktop integration, Bitcoin services, and
+[nix-bitcoin](https://github.com/fort-nix/nix-bitcoin) and are now maintained
-optional self-hosting services are all maintained in this repository.
+here. Builds no longer import or fetch nix-bitcoin. Legacy `nix-bitcoin.*`
 option names and `/etc/nix-bitcoin-secrets` remain for compatibility.
 ### Development workflow
@@ -533,9 +532,9 @@ optional self-hosting services are all maintained in this repository.
 ### Technology
 - [NixOS](https://nixos.org) and [Nix flakes](https://nixos.wiki/wiki/Flakes)
-  for reproducible system configuration
+  for declarative, pinned system configuration
- [nix-bitcoin](https://github.com/fort-nix/nix-bitcoin) for declarative
+- `modules/bitcoin/` for the in-repository Bitcoin and Lightning stack
-  Bitcoin and Lightning services
+- `packages/` for Sovran-maintained package definitions and patches
 - [btc-clients-nix](https://github.com/emmanuelrosa/btc-clients-nix) for the
  Sparrow, Bisq, and Bisq 2 packages
 - [Python](https://www.python.org) and [FastAPI](https://fastapi.tiangolo.com)
@@ -625,12 +624,14 @@ sudo nixos-rebuild switch --rollback
 | `flake.nix` | Declares flake inputs, the running system, and installer outputs |
 | `flake.lock` | Pins dependencies for reproducible builds |
 | `configuration.nix` | Base host, boot, desktop, user, security, backup, and system configuration |
-| `modules/` | Core modules, Bitcoin services, self-hosted services, and optional features |
+| `modules/` | Core modules, self-hosted services, and optional features |
 | `modules/bitcoin/` | In-repository Bitcoin and Lightning service modules |
 | `modules/core/` | Roles, Hub integration, Caddy, desktop, support, and other core behavior |
 | `app/` | Sovran Hub backend, templates, static assets, scripts, and web interface |
 | `scripts/` | Automated release, build, and CDN upload utility scripts |
 | `iso/` | Installer configuration, installer code, and installer assets |
-| `packages/` | Custom package sources and patches (for example, Alby Hub) |
+| `packages/` | Sovran-maintained package definitions and patches |
 | `tests/` | Security and Nix integration checks |
 | `assets/` | Documentation images |
 | `custom.template.nix` | Template for local features and service overrides |
@@ -704,65 +705,35 @@ production environment.
 ## About Bitcoin wallet entropy
-When you create a Bitcoin wallet in Sparrow Wallet, you generate a **24-word
+Wallet recovery words control the funds. Never share them with a website,
-seed phrase**. You should also apply a **128-bit BIP39 passphrase**. These are
+support technician, cloud service, or chat application.
 **two independent entropy sources** — both are required to recover your wallet,
 and neither one alone is sufficient.
-**Create each entropy source on different hardware.**
+For meaningful balances, prefer a well-reviewed hardware signer and follow its
 verified backup process. A BIP39 passphrase is optional, advanced protection;
 it is not a replacement for the recovery words. If you use one, back it up
 separately—losing either item can make the wallet unrecoverable.
-The seed phrase is generated by Sparrow Wallet on your Sovran_SystemsOS machine.
+Keep durable offline backups in separate secure locations. Test recovery before
-The 128-bit passphrase should be generated on a separate device — for example:
+relying on a wallet, and begin with a small amount.
 - A **GrapheneOS** phone using Bitwarden's passphrase generator
 - A different computer running the **Diceware** program
 This way, no single device ever produces or holds both sources of randomness.
 If one device is ever compromised, the other entropy source remains unknown to
 an attacker. Your wallet cannot be recovered without **both**.
 This is not a recommendation against hardware wallets, dice, or any other
 well-tested method of creating entropy. Those are established and valuable
 approaches. If you use a hardware wallet, verify for yourself that its entropy
 generation — both the software and the hardware — is sound and follows best
 practices.
 The takeaway is simply this: **how your entropy is created matters, and
 generating your two entropy sources on two physically separate devices is a
 strong practice to understand before setting up a Bitcoin wallet** with the
 software included in Sovran_SystemsOS.
 **You must do your own research.** The information above is basic educational
 context to help you build your own best practices — not financial advice and not
 a substitute for your own due diligence.
 ---
 ## Security approach
-Sovran_SystemsOS is designed around local ownership and explicit control.
+Sovran_SystemsOS uses layered controls:
-Its security foundations include:
+- Pinned flake inputs and hash-pinned source archives
 - Bitcoin and Lightning modules maintained in this repository
 - Firewall enabled; public SSH and remote desktop disabled by default
 - Separate service users, systemd sandboxing, and loopback bindings where practical
 - Tor enforcement for supported Bitcoin services
 - Restricted, time-limited support access with scoped `sudo`
 - Operator-controlled public service exposure
- Reproducible builds from pinned flake inputs
+See [`SECURITY.md`](SECURITY.md) for the threat model, limitations, reporting,
- Firewall enabled by default
+and operator guidance. No operating system can protect funds after recovery
- Public SSH disabled by default
+words, administrator credentials, or the root account are compromised. Apply
- Remote desktop disabled by default
+updates and keep tested offline backups.
 - Hub authentication
 - Local-network Hub access through `sovransystemsos.local`
 - Tor integration for the Bitcoin stack
 - User-controlled service exposure
 - Declarative system configuration
 - Restricted technical-support access
 - Auditable open-source code
 No operating system can guarantee complete security. Users should still apply
 updates, protect credentials, maintain backups, secure their local network,
 and review any services they choose to expose publicly.
 Bitcoin users must also securely back up wallet seed phrases, descriptors,
 channel backups, and other recovery information. Never store your only wallet
 backup on the same computer that holds the wallet.
 ---
@@ -780,11 +751,15 @@ Sovran_SystemsOS would not have the same reliability, transparency, or reproduci
 ### nix-bitcoin
-Special thanks go to the [nix-bitcoin](https://github.com/fort-nix/nix-bitcoin) project and its [contributors](https://github.com/fort-nix/nix-bitcoin/graphs/contributors).
+The in-repository Bitcoin stack began with code adapted from
 [nix-bitcoin](https://github.com/fort-nix/nix-bitcoin), primarily from commit
 [`360e30f`](https://github.com/fort-nix/nix-bitcoin/commit/360e30fee5ba32f9fecc89bc35628195d9d2dbbe).
 It has since been narrowed to Sovran's supported services and is maintained in
 this repository. nix-bitcoin is no longer a flake input or build dependency.
-nix-bitcoin provides the declarative foundation for building and operating Bitcoin and Lightning services on NixOS. Its work makes it possible to configure complex Bitcoin infrastructure—including nodes, Electrs, Lightning, Tor integration, and related services—in a reproducible and auditable way.
+We remain grateful to the nix-bitcoin contributors for the declarative and
-
+security-focused foundation. Its MIT notice is retained in
-Sovran_SystemsOS builds upon that foundation to make this infrastructure approachable through an integrated desktop, installer, and Sovran Hub.
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
 ### Emmanuel Rosa and btc-clients-nix
@@ -859,9 +834,10 @@ license.
 > Individual upstream applications, packages, artwork, fonts, and other
 > components included with or built by Sovran_SystemsOS may have their own
 > licenses and copyright holders. The AGPL-3.0 license for this repository does
-> not replace the licenses of independent upstream projects.
+> not replace those licenses.
-Read the complete license terms in [`LICENSE`](LICENSE).
+Read [`LICENSE`](LICENSE) and
 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
 ---
@@ -1,104 +1,101 @@
-# Security Policy (SECURITY.md)
+# Security Policy
-This document outlines the security policy, vulnerability disclosure process, threat model, and security best practices for **Sovran_SystemsOS**.
+## Supported versions
---
+| Release | Supported |
 |---|:---:|
 | Latest `1.0.x` stable release | Yes |
 | `main` / `staging-dev` | Development only |
 | Older than `1.0.0` | No |
-## 1. Supported Versions
+Install the newest stable point release to receive security fixes.
-We actively monitor and patch security vulnerabilities in Sovran_SystemsOS. Because the operating system is built on [NixOS](https://nixos.org), stable releases receive security updates backported from upstream Nixpkgs as well as our custom software updates.
+## Report a vulnerability
-| Version | Supported | Notes |
+**Do not open a public issue or pull request.** Report privately through:
 |:---|:---:|:---|
 | **1.0.x** (Stable) |  Yes | Active stable release line. Patches are backported regularly. |
 | **staging-dev** |  Yes | Development line; updated frequently but may contain untested code. |
 | **Legacy (< 1.0.0)** |  No | Please upgrade to the latest stable release to ensure you have active security updates. |
---
+- [GitHub Private Vulnerability Reporting](https://github.com/naturallaw777/Sovran_SystemsOS/security/advisories/new)
 - Email: [support@sovransystems.com](mailto:support@sovransystems.com)
-## 2. Reporting a Vulnerability
+Include the affected version, impact, reproduction steps, and a minimal proof of
 concept. Never send wallet recovery words, private keys, or live credentials.
-We take the security of self-custody systems, private clouds, and communications servers extremely seriously. If you discover a vulnerability, **please do not open a public issue, forum thread, or submit a public pull request.** 
+We aim to acknowledge reports within two business days. Please allow reasonable
 time for a fix and coordinated disclosure.
-Instead, report vulnerabilities privately through one of the following secure channels:
+## Security model
-1. **Email:** Send an encrypted or plain-text email to [support@sovransystems.com](mailto:support@sovransystems.com).
+### Local-first operation
   - If sending sensitive information, please contact us first to establish a secure PGP-encrypted communication channel.
 2. **GitHub Private Vulnerability Reporting:** If you are viewing this on GitHub, you can report vulnerabilities privately via the **Security** tab of this repository under **Vulnerability reporting**.
-### What to Include in a Report:
+The Hub and core data run on operator-owned hardware. The Hub is intended for a
-To help us triage and resolve the issue quickly, please include:
+trusted local network and must not be port-forwarded to the internet. Public
- A clear description of the vulnerability and its potential impact.
+services, DDNS, software updates, and optional third-party relays require
- Step-by-step instructions to reproduce the issue (including any scripts or configuration snippets).
+external networks and are outside a “fully offline” model.
 - The version of Sovran_SystemsOS you tested (found in the Hub header or `/etc/nixos/VERSION`).
 - Any potential remediation steps or suggestions you may have.
-### Our Response and Disclosure Process:
+The local Hub currently uses HTTP. Authentication does not encrypt local network
-1. **Acknowledgment:** We will acknowledge receipt of your report within **24–48 hours** and provide a tracking reference.
+traffic, so use a trusted LAN and avoid public or guest Wi-Fi.
 2. **Triage:** We will investigate and verify the vulnerability privately. We may reach out to you for clarifying details.
 3. **Remediation:** If verified, we will develop a patch on a private security branch.
 4. **Release:** We will coordinate a release date with you and publish the patch to Gitea `stable` and GitHub `main`.
 5. **Advisory:** A public security advisory will be published, giving full credit to you for the discovery (unless you request anonymity).
-We ask that you practice **coordinated vulnerability disclosure**, giving us reasonable time to patch the vulnerability before disclosing it publicly to protect other operators' funds and data.
+### In-repository Bitcoin stack
---
+Bitcoin and Lightning modules are maintained under `modules/bitcoin/`. They were
 adapted from nix-bitcoin, but Sovran builds do not import or fetch nix-bitcoin.
 The `nix-bitcoin.*` option namespace and `/etc/nix-bitcoin-secrets` path remain
 only for upgrade compatibility.
-## 3. The Sovran_SystemsOS Security Architecture
+### Supply chain and integrity
-Understanding our underlying threat model and architectural decisions will help you evaluate the system's security.
+`flake.lock` pins flake inputs, and fetched source archives use fixed hashes.
 Builds still depend on pinned Nixpkgs, NixVim, btc-clients-nix, upstream source
 archives, and any configured binary cache. Keeping the Bitcoin modules in this
 repository reduces an external dependency; it does not remove supply-chain
 risk.
-### A. Local-First Threat Model
+The Hub integrity check verifies Nix store contents and compares the running
- **No Cloud Dependency:** Your data, keys, and credentials live entirely on your physical hardware.
+system with a build from local `/etc/nixos`. It does not authenticate the release
- **Local network Hub Access:** The Sovran Hub is served directly on your local network (`sovransystemsos.local`). It is protected by authentication and **never** automatically exposed to the public internet.
+publisher or protect against an attacker who already controls root and can
- **Localhost Auto-Login:** Auto-login to the Hub is restricted strictly to local connections from `127.0.0.1` or `::1` (e.g., when accessing it directly from the local GNOME desktop). LAN and WAN clients must authenticate via password.
+change both the system and local configuration.
-### B. Declarative & Reproducible NixOS Foundation
+### Access and service isolation
 - **No Supply Chain Drift:** Dependencies, packages, and system components are strictly pinned using Nix flakes (`flake.lock`).
 - **Reproducible Integrity Checks:** Operators can verify system integrity at any time via the Hub (`/api/security/verify-integrity`), which runs `nix store verify --all` to check binary consistency and rebuilds the system state from local files to guarantee it matches the expected configuration.
 - **Default-Hardened Base:** Firewalls are enabled by default (`networking.firewall.enable = true`), public SSH and remote desktop are disabled by default, and legacy kernel modules like `rxrpc` are blacklisted to reduce the kernel's attack surface.
-### C. Restricted Tech Support ("Zero-Trust Support")
+- Firewall enabled by default
-To prevent support staff or malicious actors from accessing your private wallets, the operating system employs a unique **"Zero-Trust Support"** architecture:
+- Public SSH and remote desktop disabled by default
- **Restricted System Account:** Support sessions use a restricted, non-root account (`sovran-support`) with heavily scoped shell access and limited `sudo` privileges (restricted strictly to viewing logs, editing configuration, and rebuilding or restarting services).
+- Separate service users and systemd sandboxing where supported
- **POSIX ACL Wallet Lockout:** Enabling support immediately triggers POSIX ACLs (`setfacl -m u:sovran-support:---`) to block the support user from reading, writing, or traversing sensitive directories (such as `/etc/nix-bitcoin-secrets`, `/var/lib/bitcoind`, `/var/lib/lnd`, and `/home`).
+- Administrative service ports bound to loopback where practical
- **User-Controlled Timed Unlock:** Support staff can *only* access wallet files if the operator explicitly grants a time-limited unlock from the Hub interface. This unlock automatically expires, re-locking the directories.
+- Tor enforced for supported Bitcoin traffic and onion services
- **Tamper-Evident Auditing:** All support actions (enabling, disabling, wallet unlocking, or locking) are logged in a tamper-evident audit trail (`/var/log/sovran-support-audit.log`) readable directly by the operator.
+- Public web services exposed only when enabled by the operator
-### D. Native Cryptographic Isolation
+Tor reduces network exposure for configured Bitcoin services. It is not a
- **Tor Network Integration:** Upstream Bitcoin services (Knots/Core, Electrs, LND) utilize native Tor integration, preventing your home IP address from leaking to the public network or third-party node providers.
+guarantee against every IP leak, application bug, or traffic-analysis attack.
 - **Isolated Lightning Wallets:** Nostr Wallet Connect (NWC) uses isolated, sandboxed Lightning wallets with specific spending limits and access presets (e.g., receive-only), keeping your main node funds completely isolated from individual apps.
---
+### Restricted support access
-## 4. Security Best Practices for Operators (Users)
+Support uses a per-session SSH key on the non-root `sovran-support` account.
 Sessions expire after 24 hours and have a small allowlist of `sudo` commands.
 Wallet paths receive deny ACLs unless the operator explicitly removes them.
 Disabling support removes the key and reapplies the ACLs.
-No software can provide absolute security. You are the ultimate sovereign of your machine. Follow these best practices to keep your system and assets secure:
+Support events are written to `/var/log/sovran-support-audit.log`. This is a
 local audit log, not a cryptographically tamper-evident record.
-### 🔑 1. Split Wallet Entropy
+## Out of scope
 When setting up a Bitcoin wallet, **generate your two entropy sources on separate, unconnected hardware**:
 - **Seed Phrase:** Generated by Sparrow Wallet on your Sovran_SystemsOS machine.
 - **BIP-39 Passphrase (128-bit):** Generated on a separate device (e.g., a GrapheneOS phone using a trusted password generator or offline Diceware dice).
 - *Why?* If either device is compromised, your wallet remains secure because an attacker needs **both** independent sources of randomness to recover it.
-### 💾 2. Implement a Robust Backup Strategy
+Sovran_SystemsOS cannot protect against:
 - **Off-Machine Backups:** Never store your only wallet backups, seed phrases, or descriptor backups on the same computer as your running wallet.
 - **Descriptor & Channel Backups:** If using Lightning (LND), regularly back up your Static Channel Backups (SCB) and store them off-site. A node hardware failure can permanently lock up channel funds without a fresh SCB.
 - **Ext4 Backups:** If using the Hub's Manual Backup utility, ensure you are backing up to a dedicated **ext4-formatted** external drive. This preserves Linux-native security metadata, permissions, and POSIX ACLs.
-### 🛡️ 3. Maintain Network and Access Hygiene
+- Compromised root or administrator credentials
- **Public SSH Off:** Keep SSH remote access disabled in the Hub unless you actively need it. If enabled, Fail2Ban is active, but you should still enforce a strong system password.
+- Stolen recovery words, private keys, or backups
- **Strong Diceware Passwords:** Ensure the system `free` and `root` users have strong passphrases. Avoid re-using passwords across services.
+- Malicious or compromised hardware, firmware, or build infrastructure
- **Guest Networks:** Do not access the Sovran Hub over public or guest Wi-Fi networks. These networks often lack isolation, exposing local network traffic to other devices.
+- Services the operator deliberately exposes or weakens
- **Disable RDP When Done:** Turn off Remote Desktop (RDP) once your administrative session is finished.
+- Physical access without appropriate disk and firmware protections
-### 🧑‍💻 4. Hardening Support Sessions
+## Operator basics
 If you require technical support from Sovran Systems:
 - **Enable SSH and Support on-demand:** Only enable SSH Remote Access and Support sessions when actively working with a technician, and **disable** them immediately when the session is over.
 - **Confirm Removal:** The Hub's support page includes a "Verify Removal" feature. Always use it to ensure public keys have been fully stripped from the system.
 - **Restrict Wallet Access:** Only unlock your wallet directories if absolutely necessary for the support session, and choose the shortest possible duration. Re-lock manually as soon as the troubleshooting steps are complete.
 - **Review Audit Logs:** Periodically inspect the support audit log via the Hub interface to review exactly when support sessions were toggled or unlocked.
---
+- Verify downloads and stop if the checksum does not match.
 - Apply stable security updates promptly.
 - Use unique passwords and keep SSH/RDP off when not needed.
 - Prefer a well-reviewed hardware signer for meaningful Bitcoin balances.
 - Keep tested, offline backups in separate secure locations.
 - Never share recovery words or private keys with support.
 - Disable support access when the session ends and review the audit log.
-Thank you for helping us maintain a highly secure, private, and sovereign computing operating system!
+No software can provide absolute security. Review your configuration and threat
 model before storing important funds or data.
@@ -0,0 +1,33 @@
 # Third-Party Notices
 ## nix-bitcoin
 Portions of `modules/bitcoin/` and selected package definitions were adapted
 from [fort-nix/nix-bitcoin](https://github.com/fort-nix/nix-bitcoin), commit
 [`360e30fee5ba32f9fecc89bc35628195d9d2dbbe`](https://github.com/fort-nix/nix-bitcoin/commit/360e30fee5ba32f9fecc89bc35628195d9d2dbbe).
 The current Sovran build does not import or fetch nix-bitcoin.
 MIT License
 Copyright (c) 2019 nix-bitcoin developers
 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.
 Other packaged applications retain their own upstream licenses and copyright
 notices.