@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/docs/security/AI_ACT_COMPLIANCE.md

@@ -0,0 +1,90 @@
+# EU AI Act Compliance Assessment
+
+This document maps the dotfiles project against the EU Artificial Intelligence Act (Regulation (EU) 2024/1689) to confirm compliance posture and applicable obligations.
+
+---
+
+## Risk Classification (Annex III Assessment)
+
+| Criterion | Assessment | Result |
+|-----------|-----------|--------|
+| Biometric identification | Not applicable | N/A |
+| Critical infrastructure | Not applicable | N/A |
+| Education / employment | Not applicable | N/A |
+| Essential services | Not applicable | N/A |
+| Law enforcement | Not applicable | N/A |
+| Migration / border control | Not applicable | N/A |
+
+**Classification: Minimal Risk**
+
+This project is a workstation configuration management tool. It does not deploy, train, or host AI models. It integrates with external AI CLI tools (Claude, Gemini, Ollama) as a consumer, not a provider.
+
+---
+
+## Open-Source Exemption (Article 2(12))
+
+| Requirement | Status |
+|-------------|--------|
+| License type | MIT (permissive, open-source) |
+| Model weights distributed | No — no model training or distribution |
+| Free and open-source | Yes — publicly available source code |
+| No prohibited practices (Article 5) | Confirmed — no subliminal, exploitative, or social scoring use |
+
+**Result:** This project qualifies for the open-source exemption under Article 2(12). Open-source AI components released under free licenses are exempt from most AI Act obligations, provided they do not fall under prohibited practices or high-risk classifications.
+
+---
+
+## Transparency Obligations
+
+Even for minimal-risk and exempt systems, the AI Act encourages transparency. This project voluntarily implements the following:
+
+| Obligation | Implementation | Evidence |
+|-----------|----------------|----------|
+| AI interaction disclosure | Agent session logging | `agent-sessions.jsonl` via `dot_agent_session_log()` |
+| Model identification | Model registry | `dot_config/dotfiles/model-registry.json` |
+| Configuration transparency | Agent profiles | `dot_config/dotfiles/agent-profiles.json` |
+| Audit trail | Structured logging | `~/.local/share/dotfiles.log`, `~/.local/state/dotfiles/` |
+| Workstation attestation | Attestation export | `dot attest --json` |
+
+---
+
+## GPAI Provisions (Chapter V)
+
+| Criterion | Assessment |
+|-----------|-----------|
+| General-purpose AI model provider | **No** — this project does not train, fine-tune, or distribute AI models |
+| Systemic risk model | **No** — no model hosting or inference serving |
+| Downstream provider obligations | **No** — consumer of external AI APIs only |
+
+**Result:** GPAI provisions are not applicable. This project consumes AI services but does not provide them.
+
+---
+
+## Enforcement Timeline
+
+| Milestone | Date | Relevance |
+|-----------|------|-----------|
+| AI Act entered into force | August 1, 2024 | Awareness |
+| Prohibited practices apply | February 2, 2025 | Confirmed no prohibited use |
+| GPAI rules apply | August 2, 2025 | Not applicable |
+| High-risk obligations apply | **August 2, 2026** | Not applicable (minimal risk) |
+| Full enforcement | August 2, 2027 | Maintain compliance posture |
+
+**Next review:** Before August 2026 enforcement date — reassess if project scope changes to include model hosting or high-risk use cases.
+
+---
+
+## Cross-References
+
+| Document | Relevance |
+|----------|-----------|
+| [COMPLIANCE.md](COMPLIANCE.md) | SOC 2, ISO 27001, GDPR framework mapping |
+| [THREAT_MODEL.md](THREAT_MODEL.md) | Trust boundaries and attack surface |
+| [MCP_POLICY.md](MCP_POLICY.md) | MCP governance and supply-chain controls |
+| [SECURITY.md](SECURITY.md) | Core security model |
+
+---
+
+## Summary
+
+This project is classified as **minimal risk** under the EU AI Act and qualifies for the **open-source exemption** under Article 2(12). No mandatory obligations apply. Transparency measures are voluntarily implemented through agent session logging, model registry, and workstation attestation.

package/docs/security/AUTOMATION_SECRETS.md

@@ -0,0 +1,22 @@
+# Automation Secrets
+
+## Required secrets
+
+| Secret | Scope | Purpose |
+| :--- | :--- | :--- |
+| `ACTIONS_BOT_SIGNING_KEY` | GitHub Actions | SSH private key used for signed automation commits |
+| `GITHUB_TOKEN` | GitHub Actions | GitHub API access for PRs, attestations, and scans |
+
+## Required local variables
+
+| Variable | Scope | Purpose |
+| :--- | :--- | :--- |
+| `HOMEBREW_INSTALLER_SHA256` | macOS bootstrap | Verifies the Homebrew installer before execution |
+| `CHEZMOI_INSTALLER_SHA256` | Installer | Verifies the Chezmoi installer before execution |
+
+## Provisioning notes
+
+1. Store the SSH signing private key in GitHub Actions as `ACTIONS_BOT_SIGNING_KEY`.
+2. Store the matching public key in [allowed_signers](/home/seb/.dotfiles/dot_config/git/allowed_signers).
+3. Rotate the key on personnel or workstation change.
+4. Fail closed when secrets are absent.

package/docs/security/COMPLIANCE.md

@@ -0,0 +1,453 @@
+# Compliance Architecture
+
+This document describes the compliance, security, and cross-platform compatibility controls implemented in this repository, mapped to standard regulatory frameworks (SOC 2, ISO 27001, GDPR).
+
+## Overview
+
+| Framework | Status | Description |
+|-----------|--------|-------------|
+| SOC 2 Type II | Aligned | Security, availability, and confidentiality |
+| ISO 27001 | Aligned | Information security management controls |
+| GDPR/HIPAA | Aligned | Privacy and data protection |
+| ISO 13485 | Aligned | Risk management (FMEA), verification & validation |
+| ALCOA | Implemented | Audit trail integrity |
+| EU AI Act | Exempt | Minimal risk, open-source exemption (Article 2(12)) |
+
+---
+
+## EU AI Act (Regulation (EU) 2024/1689)
+
+| Requirement | Status | Implementation |
+|-------------|--------|----------------|
+| **Risk classification** | Minimal risk | No high-risk use cases (Annex III) |
+| **Open-source exemption** | Applicable | MIT license, no model weights distributed (Article 2(12)) |
+| **Prohibited practices** | Confirmed none | No subliminal, exploitative, or social scoring use (Article 5) |
+| **Transparency** | Voluntary | Agent session logging, model registry, attestation |
+| **GPAI provisions** | Not applicable | Consumer of AI APIs, not a provider |
+
+See [AI_ACT_COMPLIANCE.md](AI_ACT_COMPLIANCE.md) for full assessment.
+
+---
+
+## Regulatory Mapping
+
+### SOC 2 Type II
+
+| Control | Description | Implementation |
+|---------|-------------|----------------|
+| **CC6.1** | Logical Access Security | `zsh` restricted permissions, SSH key management via `1Password`/Agents |
+| **CC6.8** | Unauthorized Code Protection | GPG/SSH signed commits, `slsa-framework` workflow |
+| **CC7.1** | System Operations | `compliance-guard.yml` blocks insecure patterns |
+| **CC7.2** | Change Detection | Pre-commit hooks detect security violations |
+| **CC8.1** | Change Management | Git-based IaC, PR templates, CODEOWNERS |
+| **A1.2** | Audit Logs | `~/.local/share/dotfiles.log` tracks operations |
+
+### ISO 27001
+
+| Control | Description | Implementation |
+|---------|-------------|----------------|
+| **A.9.1.1** | Access Control Policy | Principle of Least Privilege (umask 022/077) |
+| **A.9.4.1** | Information Access Restriction | `chmod 777/666` blocked by CI |
+| **A.12.1.2** | Change Management | Git version control with CI/CD verification |
+| **A.12.6.1** | Technical Vulnerability Management | Gitleaks, TruffleHog secrets scanning |
+| **A.13.1.1** | Network Controls | TLS enforcement (no `curl -k`) |
+| **A.14.2.5** | Secure Engineering | ShellCheck, cross-platform testing |
+| **A.14.2.8** | System Security Testing | Module coverage gate (>=95%, currently 100%), weekly scans |
+
+### GDPR / HIPAA (Privacy)
+
+| Requirement | Description | Implementation |
+|-------------|-------------|----------------|
+| **Data Minimization** | Limit data collection | `privacy-mode` disables CLI telemetry |
+| **Integrity** | Protect against tampering | `lock-configs` prevents modification |
+| **Encryption** | Protect data at rest | Age encryption for sensitive dotfiles |
+
+---
+
+## Security Controls
+
+### TLS Enforcement
+
+All network operations require valid TLS certificates:
+
+| Control | Pattern Blocked | Enforcement |
+|---------|-----------------|-------------|
+| Insecure curl | `curl -k`, `--insecure` | Pre-commit + CI |
+| Certificate bypass | `wget --no-check-certificate` | Pre-commit + CI |
+| Plaintext HTTP | `http://` URLs | CI warning |
+
+**Files:**
+- Pre-commit: `config/pre-commit-config.yaml`
+- CI: `.github/workflows/compliance-guard.yml`
+
+### Secrets Management
+
+| Tool | Purpose | Configuration |
+|------|---------|---------------|
+| Gitleaks | Prevent secrets in commits | `config/gitleaks.toml` |
+| TruffleHog | Deep secrets scanning | CI workflow |
+| detect-secrets | Baseline secrets detection | `.secrets.baseline` |
+| Age | Encrypt sensitive dotfiles | Chezmoi integration |
+
+### Permission Controls
+
+| Control | Implementation |
+|---------|----------------|
+| Least privilege CI | `permissions: contents: read` default |
+| No world-writable | `chmod 777/666` blocked by CI |
+| CODEOWNERS | All paths mapped to reviewers |
+| Signed commits | GPG signing enforced |
+
+### Dangerous Pattern Blocking
+
+Patterns automatically blocked by CI and pre-commit hooks:
+
+```bash
+# Blocked - insecure TLS
+curl -k https://...
+wget --no-check-certificate https://...
+
+# Blocked - world-writable permissions
+chmod 777 /path
+chmod -R 666 /files
+
+# Blocked - hardcoded credentials
+password="literal_value"
+```
+
+---
+
+## Cross-Platform Compatibility
+
+### Supported Platforms
+
+| Platform | Tools | Default Shell | Bash Version |
+|----------|-------|---------------|--------------|
+| Linux | GNU | Bash | 5.x |
+| macOS | BSD | Zsh | 3.2 (system) |
+| WSL | GNU | Bash | 5.x |
+
+### Line Ending Normalization
+
+Configured in `.gitattributes`:
+
+| Pattern | Line Ending | Reason |
+|---------|-------------|--------|
+| `*.sh` | LF | Unix scripts |
+| `*.bash` | LF | Unix scripts |
+| `*.zsh` | LF | Unix scripts |
+| `*.bat` | CRLF | Windows batch |
+| `*.ps1` | CRLF | PowerShell |
+
+### BSD vs GNU Compatibility
+
+The `cross-platform-test.yml` workflow validates scripts on both platforms:
+
+| Pattern | Issue | Portable Alternative |
+|---------|-------|---------------------|
+| `sed -i ''` | BSD requires backup ext | Check `$OSTYPE` |
+| `sed -i` | GNU style | Check `$OSTYPE` |
+| `grep -P` | GNU-only PCRE | Use `grep -E` |
+| `date -d` | GNU-only | Use `date +%s` |
+| `readarray` | Bash 4+ only | Use `while read` |
+| `declare -A` | Bash 4+ only | Use indexed arrays |
+
+### Path Handling
+
+| Requirement | Implementation |
+|-------------|----------------|
+| No hardcoded user paths | Use `$HOME` or `~` |
+| Case-insensitive safe | No filename collisions |
+| Cross-platform paths | No platform-specific path literals |
+
+---
+
+## CI/CD Pipeline
+
+### Workflow Matrix
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `ci.yml` | Push/PR | Full CI pipeline, ShellCheck, tests |
+| `compliance-guard.yml` | Push/PR | Security pattern scanning |
+| `cross-platform-test.yml` | Push/PR + weekly | BSD/GNU compatibility |
+| `security-enhanced.yml` | Push/PR | Deep security analysis, SBOM |
+| `codeql.yml` | Push/PR + weekly | Static code analysis |
+| `sbom-diff.yml` | Pull request | SBOM diff and CVE correlation |
+| `nightly.yml` | Daily 2 AM UTC | Dependency version checks |
+
+### Compliance Guard Jobs
+
+```text
+compliance-guard.yml
+├── insecure-patterns     # TLS, credentials, chmod
+├── portability           # ShellCheck, paths, .gitattributes
+├── dockerfile-lint       # Hadolint
+└── compliance-summary    # Report generation
+```
+
+### Cross-Platform Test Jobs
+
+```text
+cross-platform-test.yml
+├── ubuntu-latest (GNU)   # Linux compatibility
+├── macos-latest (BSD)    # macOS compatibility
+└── compatibility-report  # Summary
+```
+
+### GitHub Actions Security
+
+| Control | Implementation |
+|---------|----------------|
+| Pinned versions | All actions pinned to SHA or version |
+| Minimal permissions | `contents: read` by default |
+| Concurrency control | Cancel in-progress duplicates |
+| Timeout limits | All jobs have explicit timeouts |
+
+---
+
+## Pre-Commit Hooks
+
+### Configuration
+
+File: `config/pre-commit-config.yaml`
+
+### Hook Matrix
+
+| Hook | Stage | Purpose |
+|------|-------|---------|
+| `shellcheck` | commit | Shell script linting |
+| `shfmt` | commit | Shell script formatting |
+| `gitleaks` | commit | Secrets detection |
+| `detect-secrets` | commit | Credential scanning |
+| `checkov` | commit | Infrastructure security |
+| `hadolint` | commit | Dockerfile linting |
+| `insecure-tls-check` | commit | Block `curl -k` |
+| `dangerous-chmod-check` | commit | Block `chmod 777/666` |
+| `security-policy-enforcement` | pre-push | Policy validation |
+
+### Installation
+
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit install --hook-type pre-push
+```
+
+---
+
+## Change Management
+
+### Pull Request Requirements
+
+| Requirement | Implementation |
+|-------------|----------------|
+| PR template | `.github/PULL_REQUEST_TEMPLATE.md` |
+| Code owners | `.github/CODEOWNERS` |
+| CI checks | Required to pass |
+| Review required | Auto-assigned via CODEOWNERS |
+
+### PR Template Checklist
+
+```markdown
+- [ ] `chezmoi apply --dry-run` verified
+- [ ] Manual testing on macOS
+- [ ] Manual testing on Linux
+- [ ] CI checks pass
+```
+
+### Commit Requirements
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Signed commits | GPG/SSH signing (cryptographically verified) |
+| Conventional format | `feat:`, `fix:`, `docs:` prefixes |
+| Co-author attribution | AI contributions attributed |
+
+### Cryptographic Identity Verification (ALCOA: Attributable)
+
+For SOC 2 compliance, the "Attributable" principle requires that all changes are linked to a **verified cryptographic identity**, not just a username.
+
+**Enforcement layers:**
+
+| Layer | Mechanism | Status |
+|-------|-----------|--------|
+| Local | Pre-push hook blocks unsigned commits | Enforced |
+| CI | `compliance-guard.yml` verifies signatures | Advisory |
+| GitHub | Branch protection (optional) | Configurable |
+
+**Pre-push hook location:** `scripts/git-hooks/pre-push`
+
+```bash
+# The hook verifies each commit before push:
+for c in $(git rev-list "$range"); do
+  if ! git verify-commit "$c" >/dev/null 2>&1; then
+    echo "Blocked: unsigned commit $c"
+    exit 1
+  fi
+done
+```
+
+**Setup signing:**
+
+```bash
+# SSH signing (recommended)
+git config --global gpg.format ssh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global commit.gpgsign true
+
+# GPG signing (alternative)
+git config --global user.signingkey <YOUR_GPG_KEY_ID>
+git config --global commit.gpgsign true
+
+# Or use the dotfiles alias:
+enable-signing ssh  # or: enable-signing gpg
+```
+
+**Install pre-push hook:**
+
+```bash
+cp scripts/git-hooks/pre-push .git/hooks/pre-push
+chmod +x .git/hooks/pre-push
+```
+
+**GitHub Branch Protection (recommended):**
+
+Enable "Require signed commits" in repository settings:
+`Settings > Branches > Branch protection rules > Require signed commits`
+
+---
+
+## Test Coverage
+
+### Current Metrics
+
+| Category | Count | Coverage |
+|----------|-------|----------|
+| Documentation files | 63 | Audited |
+| Executable shell surfaces | 205 | Audited |
+| Unit test files | 425 | Tested |
+| Integration test files | 11 | Tested |
+| **Total test files** | **436** | **Module coverage: 100% (threshold >=95%)** |
+| **Named tests (`test_start`)** | **2149** | **Pass rate: 100%** |
+
+### Test Framework
+
+```text
+tests/
+├── framework/
+│   ├── assertions.sh    # 16 assertion functions
+│   ├── mocks.sh         # Mock utilities
+│   └── test_runner.sh   # Test executor
+├── unit/
+│   └── test_*.sh        # 378 unit test files
+├── integration/
+│   └── test_*.sh        # 9 integration test files
+└── performance/
+    └── benchmark_runner.sh
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+./tests/framework/test_runner.sh
+
+# Run specific test
+bash tests/unit/test_dot_commands_apply.sh
+```
+
+---
+
+## Security Documentation
+
+### Required Files
+
+| File | Purpose | Location |
+|------|---------|----------|
+| SECURITY.md | Vulnerability reporting | `.github/SECURITY.md` |
+| CONTRIBUTING.md | Contribution guidelines | `.github/CONTRIBUTING.md` |
+| CODEOWNERS | Code ownership | `.github/CODEOWNERS` |
+| INCIDENT_RESPONSE.md | Incident response plan | `docs/security/` |
+| FMEA.md | Failure Mode & Effects Analysis | `docs/security/` |
+| VERIFICATION_VALIDATION.md | ISO 13485-style V&V report | `docs/security/` |
+| .editorconfig | Editor settings | Root |
+| .gitattributes | Git attributes | Root |
+
+### Vulnerability Response SLA
+
+| Severity | Initial Response | Resolution Target |
+|----------|------------------|-------------------|
+| Critical | 24 hours | 48 hours |
+| High | 72 hours | 7 days |
+| Medium | 5 business days | 30 days |
+| Low | 10 business days | 90 days |
+
+---
+
+## Audit & Forensics
+
+### Immutability
+
+Lock critical configuration files:
+
+```bash
+lock-configs  # Sets chflags uchg (macOS) or chattr +i (Linux)
+```
+
+### Audit Trail
+
+```bash
+# View dotfiles operations log
+dot audit
+
+# Log location
+~/.local/share/dotfiles.log
+```
+
+### Supply Chain Security
+
+| Control | Implementation |
+|---------|----------------|
+| SBOM | Generated for every release (SPDX) |
+| Provenance | SLSA Level 3 build attestation |
+| Dependencies | Pinned versions, weekly updates |
+
+---
+
+## Verification Commands
+
+### Manual Verification
+
+```bash
+# Run all pre-commit hooks
+pre-commit run --all-files
+
+# Run unit tests
+./tests/framework/test_runner.sh
+
+# Check for insecure patterns
+grep -rn --include="*.sh" -E 'curl.*-k|wget.*--no-check' .
+
+# Validate .gitattributes
+grep "text=auto" .gitattributes && echo "OK"
+```
+
+### Automated Verification
+
+| Schedule | Check |
+|----------|-------|
+| Every PR | compliance-guard, cross-platform-test |
+| Weekly | Full security scan, CodeQL |
+| Nightly | Tool version checks |
+
+---
+
+## References
+
+- [SOC 2 Type II](https://www.aicpa.org/soc2)
+- [ISO 27001:2022](https://www.iso.org/standard/27001)
+- [OWASP Top 10](https://owasp.org/Top10/)
+- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
+- [ShellCheck Wiki](https://www.shellcheck.net/wiki/)
+- [SLSA Framework](https://slsa.dev/)

package/docs/security/ENCRYPTION.md

@@ -0,0 +1,52 @@
+# Secrets Encryption with SOPS and age
+
+## Quick Start
+
+```bash
+# 1. Generate an age key (one-time)
+mkdir -p ~/.config/sops/age
+age-keygen -o ~/.config/sops/age/keys.txt
+
+# 2. Get your public key
+age-keygen -y ~/.config/sops/age/keys.txt
+# Output: age1abc123...
+
+# 3. Update .sops.yaml with your public key
+# Replace the placeholder key in .sops.yaml with your actual public key
+
+# 4. Encrypt a file
+sops --encrypt --age $(age-keygen -y ~/.config/sops/age/keys.txt) secrets.yaml > secrets.sops.yaml
+
+# 5. Edit encrypted files
+sops secrets.sops.yaml
+```
+
+## Key Management
+
+- **Private key**: `~/.config/sops/age/keys.txt` — never commit this file.
+- **Public key**: Safe to share. It lives in `.sops.yaml`.
+- **Backup**: Keep your private key in a password manager or a hardware security module.
+
+## Recovery
+
+If you lose your age private key, follow these steps:
+1. Create a new key: `age-keygen -o ~/.config/sops/age/keys.txt`
+2. Re-encrypt all secrets with the new public key.
+3. Update `.sops.yaml` with the new public key.
+
+## Integration with Chezmoi
+
+Chezmoi has built-in support for age encryption.
+
+```bash
+chezmoi add --encrypt ~/.ssh/config
+```
+
+This encrypts the file in the source state. It uses the age key set in `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+encryption = "age"
+[age]
+identity = "~/.config/sops/age/keys.txt"
+recipient = "age1abc123..."
+```