# Security and Trust Model

This document outlines the security architecture, trust boundaries, and assumptions of the Bos55 NixOS deployment pipeline. This model is designed to support a multi-member infrastructure team and remains secure even if the repository is published publicly.

## Trust Zones

The system is partitioned into three distinct trust zones, each with specific controls to prevent lateral movement and privilege escalation.

### 🔴 Zone 1: Trusted Maintainers (Source of Truth)
*   **Actors:** Infrastructure Team / Maintainers.
*   **Capabilities:** 
    *   Full access to the Git repository.
    *   Ownership of `sops-nix` master keys (GPG or Age).
    *   Direct root access to NixOS hosts via personal SSH keys for emergency maintenance.
*   **Trust:** Root of trust. All changes must originate from or be approved by a Trusted Maintainer.
*   **Security Controls:**
    *   **Signed Commits:** All contributions must be cryptographically signed by a trusted GPG/SSH key to be eligible for deployment.
    - **MFA:** Hardware-based multi-factor authentication for repository access.
    - **Metadata Redaction:** Sensitive identifiers like SSH `authorizedKeys` are stored in `sops-nix`. This prevents **infrastructure fingerprinting**, where an attacker could link your public keys to your personal identities or other projects.

### 🟡 Zone 2: CI/CD Pipeline (Automation Layer)
*   **Actor:** GitHub Actions / Forgejo Runners.
*   **Capabilities:**
    *   Builds Nix derivations from the repository.
    *   Access to the `DEPLOY_SSH_KEY` (allowing SSH access to the `deploy` user on target hosts).
    *   **Trusted Signers:** The public keys for verifying signatures are stored as a **Runner Secret** (`TRUSTED_SIGNERS`). This hides the identities of the infrastructure team even in a public repository.
    *   **NO ACCESS** to `sops-nix` decryption keys. Secrets remain encrypted during the build.
*   **Security Controls:**
    *   **Signature Enforcement:** The `deploy.yml` workflow verifies the cryptographic signature of every maintainer commit. Deployment is aborted if the signature is missing or untrusted.
    *   **Sandboxing:** Runners execute in ephemeral, isolated containers. 
    *   **Branch Protection:** Deployments to production (`main`) require approved Pull Requests. 
    *   **Fork Protection:** CI workflows (and secrets) are explicitly disabled for forks.

### 🟢 Zone 3: Target NixOS Hosts (Runtime)
*   **Actor:** Production, Testing, and Service nodes.
*   **Capabilities:** Decrypt secrets locally using host-specific `age` keys.
*   **Trust:** Consumers of builds. They trust Zone 2 only for the pushing of store paths and triggering activation scripts.
*   **Security Controls:**
    *   **Restricted `deploy` User:** The SSH user for automation is non-root. Sudo access is strictly policed via `sudoers` rules to allow only `nix-env` and `switch-to-configuration`.
    *   **Immutable Store:** Building on Nix ensures that the system state is derived from a cryptographically hashed store, preventing unauthorized local modifications from persisting across reboots.

---

## Security Assumptions & Policies

### 1. Public Repository Safety
The repository is designed to be safe for public viewing. No unencrypted secrets should ever be committed. The deployment pipeline is protected against "malicious contributors" via:
- **Mandatory PR Reviews:** No code can reach the `main` branch without peer review.
- **Secret Scoping:** Deployment keys are only available to authorized runs on protected branches.

### 2. Supply Chain & Dependencies
- **Flake Lockfiles:** All dependencies (Nixpkgs, `deploy-rs`, etc.) are pinned to specific git revisions.
- **Renovate Bot:** Automated version upgrades allow for consistent tracking of upstream changes, though they require manual review or successful status checks for minor/patch versions.

### 3. Signed Commit Enforcement
To prevent "force-push" attacks or runner compromises from injecting malicious code into the history, the pipeline should be configured to only deploy commits signed by a known "Trusted Maintainer" key. This ensures that even if a git account is compromised, the attacker cannot deploy code without the physical/cryptographic signing key.

---

## Trust Boundary Diagram

```mermaid
graph TD
    subgraph "Zone 1: Trusted Workstations"
        DEV["Maintainers (Team)"]
        SOPS_KEYS["Master SOPS Keys"]
        SIGN_KEYS["Signing Keys (GPG/SSH)"]
    end

    subgraph "Zone 2: CI/CD Runner (Sandboxed)"
        CI["Automated Runner"]
        SSH_KEY["Deploy SSH Key"]
    end

    subgraph "Zone 3: NixOS Target Hosts"
        HOST["Target Host"]
        HOST_AGE["Host Age Key"]
    end

    DEV -- "Signed Push / PR" --> CI
    CI -- "Push Store Paths & Activate" --> HOST
    HOST_AGE -- "Local Decrypt" --> HOST
    
    style DEV fill:#f96,stroke:#333
    style CI fill:#ff9,stroke:#333
    style HOST fill:#9f9,stroke:#333
```

## Security Best Practices for Maintainers

1.  **Keep Master Keys Offline:** Never store `sops-nix` master keys on the CI runner or public servers.
2.  **Audit Runner Logs:** Periodically review CI execution logs for unexpected behavior.
3.  **Rotate Deployment Keys:** Rotate the `DEPLOY_SSH_KEY` if maintainer membership changes significantly.