docs: Add Nexus deployment README

deploy/nexus/README.md

@@ -0,0 +1,81 @@
+# Componenti di Sistema — Gestione Sincronizzazione e Automazione Genoma
+
+Questo modulo contiene gli script di backend che vengono installati sul server `nexus` per gestire il ciclo di vita dei vault locali (scratch di lavoro), l'integrazione con Syncthing e l'autocommit dei file grezzi (`raw/`) provenienti dai dispositivi mobili o desktop (es. Obsidian).
+
+## Architettura dei File di Sistema
+
+Gli script sono progettati per girare in un ambiente multi-utente protetto, dove l'istanza globale di `n8n` (tramite l'utente di sistema `n8n-runner`) pilota le operazioni senza possedere i diritti di lettura/scrittura diretti sui file del genoma o sui segreti di configurazione.
+
+### 1. Posizionamento e Permessi degli Script
+
+I file inclusi in questa cartella devono essere installati sul server di produzione nella directory `/usr/local/bin/` con privilegi di esecuzione globali, ma modificabili solo da `root`.
+
+- **Destinazione:** `/usr/local/bin/`
+- **Proprietario (Owner):** `root:root`
+- **Permessi (Chmod):** `0755` (`-rwxr-xr-x`)
+
+#### Elenco degli Script:
+
+- `ensure-genome-vault`: Script idempotente che inizializza o riallinea il vault locale clonandolo da Forgejo (in loopback) sul branch `develop`, configura gli `.stignore` ed effettua il provisioning automatico della cartella condivisa su Syncthing via API.
+- `genome-askpass`: Helper di autenticazione per Git (`GIT_ASKPASS`). Intercetta le richieste di credenziali di Git durante i cloni e i push HTTP su Forgejo, iniettando l'utente e il token applicativo senza esporli nei log di sistema o negli argomenti dei processi.
+- `genome-raw-commit`: Script di polling periodico invocato da n8n. Isola i file modificati nella cartella `raw/`, interroga Syncthing per capire quale dispositivo (e quindi quale autore umano) ha generato la modifica, crea commit atomici attribuiti al singolo autore e pusha le modifiche su Forgejo (`develop`).
+
+---
+
+## Modello di Sicurezza e Visibilità
+
+Per garantire l'isolamento del sistema operativo, l'infrastruttura si basa su tre livelli di confinamento:
+
+### A. Variabili d'Ambiente Protette (`.env`)
+
+Le credenziali (Token Forgejo, API Key Syncthing) risiedono nella Home dell'utente operativo del servizio (`homelab`) e sono completamente invisibili a n8n e ad altri utenti del sistema.
+
+- **Path:** `/home/homelab/.config/knowledge-genome.env`
+- **Permessi:** `0600` (`-rw-------`), di proprietà esclusiva di `homelab:homelab`.
+
+#### env
+
+Nella cartella `~/.config/knowledge-genome.env`.
+
+```text
+# knowledge-genome.env Configuration Profile
+# Requirements: Must be owned by the service user with 0600 permissions.
+
+# Vault path and operational branch
+GENOME_VAULTS_ROOT=/srv/genome-vaults
+GENOME_BASE=develop
+
+# Forgejo Target Instance
+# Replace 127.0.0.1 with vm101 IP if Forgejo is hosted on the virtual machine
+FORGEJO_HOST=127.0.0.1:3001
+FORGEJO_OWNER=Keru
+FORGEJO_USER=n8n-bot
+FORGEJO_TOKEN="............"
+
+# Git Commit Identity
+COMMITTER_NAME=n8n-bot
+COMMITTER_EMAIL=n8n-bot@homelab
+DEFAULT_AUTHOR_NAME="Matteo Cherubini"
+DEFAULT_AUTHOR_EMAIL=matteo@keruhomelab.com
+
+# Syncthing Target Instance
+# Replace 127.0.0.1 with vm101 IP if Syncthing API is hosted on the virtual machine
+SYNCTHING_URL=http://127.0.0.1:8384
+SYNCTHING_API_KEY="............"
+```
+
+### B. Confine dei Privilegi in Sudoers
+
+L'utente di automazione `n8n-runner` (usato dall'agente SSH di n8n) non ha accesso alla shell e non può invocare comandi arbitrari. Può unicamente chiamare i due script principali impersonando l'utente `homelab` senza l'inserimento della password.
+
+Configurazione da applicare in `/etc/sudoers.d/n8n-genome` (con permessi rigorosi `0440`):
+
+```text
+n8n-runner ALL=(homelab) NOPASSWD: /usr/local/bin/ensure-genome-vault, /usr/local/bin/genome-raw-commit
+```
+
+### C. Directory dei Vault
+
+I dati veri e propri sincronizzati da Syncthing risiedono isolati in `/srv/genome-vaults/`.
+
+- **Proprietario**: homelab:homelab (UID/GID 1000), permettendo la convivenza nativa e fluida tra il demone Syncthing in esecuzione nel container e gli script Git locali.