obscurIA — connettore n8n (macOS, Apple Silicon)
==========================================

COSA SERVE PRIMA DI INIZIARE
-----------------------------
Una licenza obscurIA attiva SULLO STESSO COMPUTER dove eseguirai questi due
programmi (obscuria-bridge, obscuria-ingress). Non è una licenza separata:
è la stessa che l'app desktop ha già attivato su quel dispositivo — il
connettore la legge da sola, non c'è nulla da configurare per la licenza.

Se n8n gira su un server diverso dal computer con obscurIA installato e
attivato, il connettore su quel server non troverà nessuna licenza e si
rifiuterà di funzionare. È il comportamento corretto, non un guasto: vanno
sullo stesso dispositivo.

SULLA FIRMA E LA VERIFICA DI APPLE
-------------------------------------
I due eseguibili sono firmati con lo stesso certificato Developer ID
dell'app desktop e notarizzati da Apple (Apple ha esaminato il pacchetto
e non vi ha trovato codice malevolo noto).

C'è una differenza rispetto all'app desktop: quella è distribuita come
.dmg, dove il ticket di notarizzazione resta allegato al file e la verifica
avviene senza rete. Questi due programmi sono file sciolti in uno zip —
Apple non supporta l'allegazione del ticket per quel formato — quindi al
PRIMO avvio di ciascuno serve una connessione a internet: il sistema
verifica online con Apple invece che offline. Dagli avvii successivi non
serve più.

SE LO ESEGUI COME SERVIZIO, SENZA NESSUNO DAVANTI
----------------------------------------------------
obscuria-bridge e obscuria-ingress leggono la chiave locale dal portachiavi
di macOS, la stessa che usa l'app desktop. Il portachiavi però presuppone una
sessione utente: se avvii questi programmi come servizio al boot (launchd),
senza nessuno connesso, la chiamata non fallisce — resta appesa, in attesa di
un'autorizzazione che nessuno darà.

In quel caso imposta:

  OBSCURIA_CHIAVE_SOLO_FILE=1

così la chiave viene letta da un file invece che dal portachiavi.

ATTENZIONE, e va saputo prima: se l'app desktop su quella macchina ha messo
la propria chiave nel portachiavi, quella del file è una chiave DIVERSA — e
il connettore non riuscirà a leggere la licenza attivata dall'app. Su un Mac
dove usi entrambi, lascia stare questa variabile e avvia il connettore da una
sessione normale.

1. VERIFICA L'IMPRONTA
-------------------------
Confrontala con quella pubblicata sul sito (contro SHA256SUMS.txt incluso):

  shasum -a 256 obscuria-bridge obscuria-ingress

2. IL NODO N8N
---------------
Nella cartella dati di n8n (di solito ~/.n8n/custom, da creare se non
esiste), installa il pacchetto dal tarball incluso in questo archivio
(NON dalla cartella estratta — un'installazione da cartella crea un
collegamento simbolico che rompe la ricerca di "n8n-workflow"):

  mkdir -p ~/.n8n/custom
  cd ~/.n8n/custom
  npm install /percorso/dove/hai/estratto/questo/pacchetto/n8n-nodes-obscuria-0.1.0.tgz

Riavvia n8n. Il nodo "obscurIA" comparirà nell'elenco dei nodi disponibili.

3. I DUE ESEGUIBILI
---------------------
obscuria-bridge  — lo richiama il nodo stesso, dentro il flusso.
obscuria-ingress — va avviato a parte, DAVANTI al flusso n8n (vedi sotto
                   il perché: un nodo da solo non basta).

Rendili eseguibili e raggiungibili:

  chmod +x obscuria-bridge obscuria-ingress
  sudo cp obscuria-bridge obscuria-ingress /usr/local/bin/

Se preferisci non copiarli nel PATH, nel nodo n8n imposta "Percorso del
motore" con il percorso completo di obscuria-bridge.

4. PERCHÉ SERVE ANCHE obscuria-ingress, NON SOLO IL NODO
------------------------------------------------------------
n8n conserva ciò che riceve nella propria cronologia di esecuzione, anche
in caso di errore — è così che funziona un motore di automazione pensato
per poter ripetere un passo fallito. Un nodo obscurIA messo DENTRO il
flusso arriva sempre un istante troppo tardi: n8n ha già visto il
documento originale prima che il nodo lo protegga.

obscuria-ingress va messo DAVANTI al flusso: riceve il documento per primo,
lo protegge, e solo il testo già protetto arriva a n8n (via webhook, o
restituito a chi ha chiamato). Per collaudarlo senza inoltrare a nulla:

  OBSCURIA_INGRESS_ASCOLTO=127.0.0.1:8477 ./obscuria-ingress

Con una destinazione (il webhook del tuo flusso n8n):

  OBSCURIA_INGRESS_DESTINAZIONE=http://localhost:5678/webhook/il-tuo-flusso \
  ./obscuria-ingress

Resta in ascolto solo su 127.0.0.1 finché non lo configuri diversamente,
di proposito: da lì entrano documenti in chiaro.

5. FLUSSI DI ESEMPIO
----------------------
Nella cartella esempi/, tre flussi pronti da importare in n8n
(Workflows → Import from File):

  01-testo-verso-ai.json           — protezione reversibile verso un'AI esterna
  02-anonimizzazione-definitiva.json — nessuna mappatura, irreversibile
  03-revisione-umana.json          — il testo protetto si ferma per un controllo

Domande: scrivi a info@obscuria.it
