# Report finale audit - sophiadeveloper/mcp-servers

Data audit: 2026-06-08
Repository: `sophiadeveloper/mcp-servers`
Branch di riferimento: `master`
Branch di lavoro: `audit`
Commit base verificato: `f98098fc0683d003aea8f4ff63f05a5c8efd5c80`

## Scopo

Audit tecnico mirato su sicurezza applicativa, bug e regressioni del repository MCP workspace, con attenzione ai componenti che espongono superfici locali o modificano configurazioni utente.

Aree ispezionate con evidenza diretta:

- `README.md`
- `package.json`
- `scripts/install-user-runtime.js`
- `scripts/inject-user-mcp-settings.js`
- `scripts/gui-server.js`
- `scripts/gui/app.js`
- `scripts/runtime/apply-plan.js`
- `scripts/runtime/dependencies.js`
- `scripts/test-user-runtime.js`
- `docs/audit/final-audit-2026-06-08.md`

Nota operativa: il checkout diretto via rete dal container non era disponibile (`CONNECT tunnel failed, response 403`), quindi l'audit, la review e le scritture sono stati eseguiti tramite GitHub connector. Non sono stati inventati risultati di test locali non eseguiti.

## Stato branch

- `master` esiste ed e' stato usato come branch di riferimento.
- `main` non risulta presente.
- `audit` non esisteva ed e' stato creato da `master`.
- Stato finale atteso dopo questo aggiornamento: `audit` contiene i fix e il report aggiornato su branch separato, senza modifiche dirette a `master`.

## Commit prodotti

1. `c693589927cf20117f37840e5d4dcdb44a47c001` - `fix(gui): protegge endpoint di lettura con token locale`
2. `64aa39fe12793e8d3a31d9c68c8c6ddc336a7e41` - `fix(gui): preserva home analytics nella cancellazione`
3. `dededfacfe5aceff551cf8e543fe0b5d3678d701` - `docs(audit): aggiunge report finale audit`
4. `e42e1b7b1b9182f7cfec4430659e89d1a77c99f2` - `fix(gui): rende robusta verifica token locale`
5. Commit corrente - `docs(audit): aggiorna report dopo review`

## Ciclo review

### Review 1

Esito: findings presenti.

Findings corretti:

- parsing cookie non robusto in `scripts/gui-server.js`
- accettazione token via query string non necessaria
- report finale non aggiornato rispetto ai commit successivi

### Review 2

Esito atteso: positivo dopo il commit `fix(gui): rende robusta verifica token locale` e questo aggiornamento del report. Resta raccomandata validazione runtime/CI, non eseguibile dal container per limite di rete.

## Problemi identificati

### Medio - Endpoint locali di lettura GUI non protetti da token

File coinvolto: `scripts/gui-server.js`

Evidenza certa: gli endpoint scriventi `POST /api/install`, `POST /api/install-dependency`, `POST /api/analytics/scan` e `POST /api/analytics/delete` verificavano `X-Sophia-Gui-Token`, mentre endpoint di lettura come `/api/state`, `/api/logs`, `/api/analytics/status`, `/api/analytics/summary`, `/api/analytics/models` e `/api/analytics/events` erano accessibili senza token.

Impatto: il server ascolta su `127.0.0.1`, quindi l'esposizione e' locale. Tuttavia questi endpoint possono restituire stato runtime, differenze di installazione, metadati analytics, eventi e log di installazione. In un modello locale, processi o pagine locali non fidate potrebbero tentare accessi a dati che dovrebbero restare legati alla sessione GUI autorizzata.

Fix applicato: introdotta verifica token su tutti gli endpoint `/api/*`, non solo sui POST. Per mantenere compatibile `EventSource('/api/logs')`, che non puo' inviare header custom, `serveIndex` imposta un cookie `HttpOnly; SameSite=Strict; Path=/api` contenente lo stesso token runtime. La verifica accetta header o cookie.

Stato: corretto automaticamente.

### Medio - Parsing cookie non robusto poteva causare errore non gestito

File coinvolto: `scripts/gui-server.js`

Evidenza certa: la prima patch usava `decodeURIComponent` direttamente sui valori cookie. Un cookie malformato inviato a un endpoint `/api/*` poteva generare eccezione durante la verifica token.

Impatto: un input HTTP locale malformato avrebbe potuto interrompere la gestione della richiesta o causare instabilita' del server GUI locale.

Fix applicato: aggiunta funzione `safeDecodeCookieValue`, con fallback al valore originale quando la decodifica percent-encoding fallisce.

Stato: corretto automaticamente.

### Basso - Token accettato via query string senza necessita'

File coinvolto: `scripts/gui-server.js`

Evidenza certa: la prima patch accettava anche `?token=...` come sorgente valida del token.

Impatto: non era necessario per il client attuale e aumentava inutilmente la superficie di esposizione del token in URL, history o log locali.

Fix applicato: rimossa l'accettazione del token via query string. La GUI usa header `X-Sophia-Gui-Token` per `fetch` e cookie `HttpOnly` per `EventSource`.

Stato: corretto automaticamente.

### Basso - Rischio di regressione sul parametro `homePath` in delete analytics durante patch

File coinvolto: `scripts/gui-server.js`

Evidenza certa: durante la prima patch di hardening era stato rimosso accidentalmente il passaggio di `homePath` a `callAnalyticsTool('analytics_delete_imported', ...)`.

Impatto: la cancellazione analytics avrebbe potuto usare la home di default del processo invece della home scelta nella GUI, creando comportamento incoerente per profili custom.

Fix applicato: ripristinato `callAnalyticsTool('analytics_delete_imported', args, homePath)`.

Stato: corretto automaticamente.

## File modificati

- `scripts/gui-server.js`
- `docs/audit/final-audit-2026-06-08.md`

## Dettagli tecnici dei fix

- Aggiunte funzioni `parseCookies`, `safeDecodeCookieValue`, `tokenFromRequest` e supporto cookie `sophia_gui_token`.
- Applicata una guardia centralizzata: ogni path `/api/*` richiede token valido.
- Il token continua a essere generato per processo con `crypto.randomBytes(32)`.
- Il token continua a essere esposto alla pagina via `window.SOPHIA_GUI_TOKEN` per le chiamate `fetch` con header custom gia' presenti nel client.
- Aggiunto cookie `HttpOnly` per consentire l'autenticazione implicita dello stream SSE senza esporre ulteriormente il valore a JavaScript.
- Rimossa l'accettazione del token da query string.
- Reso robusto il parsing dei cookie contro percent-encoding malformato.
- Preservato il passaggio `homePath` verso la cancellazione analytics.

## Dipendenze aggiornate

Nessuna dipendenza aggiornata.

Motivazione: non sono emerse evidenze sufficienti, nel perimetro ispezionato, per giustificare aggiornamenti di dipendenze. La policy dell'audit evita upgrade opportunistici.

## Test eseguiti

Eseguiti tramite GitHub connector:

- verifica repository e branch: `master` presente, `main` assente, `audit` creato da `master`
- ispezione file modificati su `audit`
- review manuale del flusso token/header/cookie in `scripts/gui-server.js` e `scripts/gui/app.js`
- verifica del report finale aggiornato

Non eseguiti:

- `npm test`
- smoke test GUI locale
- test end-to-end browser su `http://127.0.0.1:3000`

Motivo: il container non poteva clonare il repository da GitHub tramite rete diretta; l'operativita' e' stata limitata al connector GitHub.

## Risultati dei test

Le verifiche disponibili confermano che:

- il branch `audit` deriva da `master`
- i fix sono confinati agli endpoint GUI locali e al report
- non sono state introdotte nuove dipendenze
- la seconda review non ha rilevato ulteriori findings correggibili in modo sicuro nel perimetro della modifica

La validazione runtime completa resta da eseguire localmente o in CI.

## Rischi residui

- Serve un test runtime della GUI per verificare che:
  - `/api/state` risponda dopo caricamento di `/`
  - `/api/state` senza token/cookie risponda `403`
  - `/api/state` con cookie malformato non causi errore non gestito
  - `/api/logs` funzioni con cookie `SameSite=Strict`
  - gli endpoint analytics continuino a rispettare `homePath`
- Il server resta una GUI locale su `127.0.0.1`; il modello di sicurezza dipende comunque dalla fiducia nel dispositivo locale.
- Non e' stato possibile completare audit esaustivo di tutti i server MCP (`analytics-node`, `sql-node`, `playwright-node`, `projectfs-node`, ecc.) per limiti di tempo/accesso file via connector.

## Problemi rinviati a revisione umana

- Valutare se gli endpoint analytics di sola lettura debbano essere ulteriormente limitati per default, ad esempio evitando `home` arbitrari fuori dalla home corrente o richiedendo conferma UI per path custom.
- Valutare l'aggiunta di test automatici specifici per `scripts/gui-server.js`, separando la creazione del server dall'avvio su porta per renderlo testabile senza side effect.
- Valutare un audit dedicato dei singoli server MCP con focus su input path, command execution, SQL access, browser automation e gestione `.env`.

## Indicazioni operative per review o merge

Prima del merge verso `master`:

1. Eseguire `npm test` dal root del repository.
2. Avviare `npm run gui` e verificare manualmente la GUI.
3. Con browser aperto su `/`, verificare che gli endpoint API funzionino.
4. Con una richiesta diretta priva di cookie/header verso `/api/state`, verificare risposta `403`.
5. Con un cookie malformato, verificare che `/api/state` non causi crash e restituisca `403` se il token non e' valido.
6. Verificare che analytics scan/delete rispettino ancora la home selezionata.

## Suggerimento PR

Titolo suggerito:

`fix(gui): protegge gli endpoint locali della GUI`

Descrizione suggerita:

```markdown
## Sintesi

Protegge tutti gli endpoint `/api/*` della GUI locale con il token runtime gia' usato per le azioni scriventi. Per lo stream SSE dei log viene impostato un cookie `HttpOnly; SameSite=Strict; Path=/api`, cosi' `EventSource` resta compatibile senza header custom.

## Dettagli

- Aggiunge verifica token centralizzata per gli endpoint API.
- Mantiene il token header per le chiamate fetch esistenti.
- Usa cookie locale per `/api/logs`.
- Rende robusto il parsing cookie contro valori malformati.
- Rimuove il token da query string.
- Preserva il parametro `homePath` nella cancellazione analytics.

## Test consigliati

- `npm test`
- `npm run gui`
- richiesta senza token a `/api/state` attesa `403`
- richiesta con cookie malformato attesa `403` senza crash
- verifica GUI e analytics con home custom
```