L'API locale

A che cosa serve

Il daemon del companion è un normale server HTTP. Espone l’account a cui ha effettuato l’accesso — connessioni, codici, inviti, tag, preset, open link, gestione dell’organizzazione — come JSON su /api/v1/.

È così che uno script, un sistema di back office o un account macchina usa Trusted Codes senza una persona e un telefono. Il daemon detiene la sessione e le chiavi; chi chiama detiene un token e parla HTTP semplice.

Dove ascolta

L’indirizzo predefinito è http://127.0.0.1:19821. Quella è l’unica voce server nel documento OpenAPI, ed è la porta fissa — solo loopback.

Due variabili d’ambiente la spostano: TCC_HTTP_BIND e TCC_HTTP_PORT. Chi chiama senza interfaccia dovrebbe rispettare entrambe piuttosto che assumere il valore predefinito.

Il fatto che la porta sia fissa è deliberato. Può essere messa in allowlist una volta e poi lasciata stare.

I due documenti

Il daemon serve due documenti OpenAPI su due percorsi, per due pubblici.

GET /api/v1/openapi.json è il documento REST tipizzato — le rotte che descrivono queste pagine. È generato dalle struct Rust che serializzano le risposte, quindi un campo non può essere scritto in un modo nel documento e in un altro sul filo. Lo stesso documento è committato nel repository, e i tipi di risposta TypeScript della UI web del companion sono generati da esso.

GET /openapi.json, sul percorso senza prefisso, è una cosa diversa: il catalogo degli strumenti MCP del daemon, per i client MCP e i GPT personalizzati. La sezione MCP copre quella superficie.

GET /api/v1/docs serve una pagina interattiva che visualizza il documento REST. Sia quella pagina sia /api/v1/openapi.json sono pubbliche — nessun token.

Salute e stato

GET /health (anche GET /api/v1/health) non richiede token. Usala per rispondere a “il daemon è attivo”. È l’unica rotta documentata che risponde prima che il daemon abbia effettuato l’accesso.

GET /api/v1/status richiede un token e risponde di più: se il daemon è autenticato, se il dispositivo è registrato, se la chiave globale è attiva, il nome dell’ambiente con cui è partito, il backend che ha effettivamente risolto, la versione del daemon, quante connessioni sono in cache, l’ultimo orario di sincronizzazione, e un riassunto in una riga.

Il nome dell’ambiente e il backend risolto sono campi separati di proposito. Un daemon avviato con un nome di ambiente può essere puntato altrove da un’override, e solo il valore risolto ti dice con chi sta davvero parlando.

Alcuni di quei campi sono null per chi chiama da macchina a macchina, che non detiene una cache locale e non è l’utente proprio del daemon. Un null lì significa “non applicabile”, non “sconosciuto”.

Prefisso del percorso e compatibilità

Gli endpoint dello strumento e di MCP sono registrati due volte: una su un percorso piatto per i client più vecchi, e una sotto /api/v1/. Le nuove integrazioni dovrebbero puntare alla forma con prefisso. I percorsi senza prefisso restano stabili per tutto il ciclo di vita di v1 e vengono rimossi solo quando esce /api/v2/.

Le rotte REST in queste pagine esistono solo sotto /api/v1/.