API

Twee API’s

Twee verschillende dingen worden hier een API genoemd, en het zijn niet dezelfde vlakken.

De lokale API hoort bij de desktopcompanion, tcc. De daemon draait op je eigen machine en bedient een HTTP-interface op het loopback-adres. Alles wat je in de companion kunt doen — drie woorden verifiëren, een bestand verzegelen, verbindingen opsommen, een organisatie beheren — heeft een route. Er is een vastgelegd OpenAPI-document, waaruit deze pagina’s zijn geschreven, en de daemon bedient datzelfde document aan aanroepers.

De platform-API is de serverkant: de gehoste dienst waarmee de apps praten. Ze is niet gepubliceerd, en draagt geen enkele gebruikersspecifieke route — zie hieronder, want de reden is bewust en geen gat.

Wat deze sectie behandelt

Deze pagina’s behandelen alleen de lokale API. Ze beschrijven waar de daemon luistert, hoe een aanroeper zich authenticeert, hoe de antwoorden eruitzien, en elk van de 79 gedocumenteerde paden.

Ze leren je niet de companion zelf. Hem installeren, aanmelden en als daemon draaien wordt behandeld op de pagina’s over de companion en de commandoregel.

Waarom de platform-API ontbreekt

De korte reden is dat ze geen gepubliceerd document heeft, geen gepubliceerde versie en geen stabiliteitsbelofte, dus pagina’s erover zouden een vlak beschrijven waaraan niemand zich heeft verbonden.

De langere reden is degene die niet zal veranderen: er zijn geen gebruikersspecifieke routes op het platform om te publiceren.

De vraag “wat is Mary’s code?” op een server beantwoorden betekent dat de server het geheim bezit dat de code oplevert. Zodra dat zo is, is de end-to-end-belofte voorbij — niet omdat iemand er misbruik van zou maken, maar omdat ze ophoudt waar te zijn. Een server die je codes KAN lezen, is een server waarvan een compromittering ieders codes leest, en geen enkele zorgvuldigheid aan onze kant verandert wat een aanvaller daarmee zou buitmaken.

Daarom bewaren we op geen enkele server die wij draaien enig gebruikersgeheim, en een gebruikersgerichte platform-API is iets dat we niet kunnen bouwen zonder dat op te geven. Wat het platform wel blootstelt, is systeemniveauwerk tussen machines onderling, dat geen persoonlijk geheim raakt, en een accounthouder heeft daar sowieso geen toegang toe.

Dit is geen gat dat ooit wordt opgevuld. Wordt de platform-API ooit gepubliceerd, dan dekt ze hetzelfde systeemniveau en bevat ze nog steeds niets van jou.

Het gevolg voor een integratie: het enige dat vragen over de verbindingen van een account kan beantwoorden, is iets dat de sleutels van dat account bezit — de lokale companion. Hij houdt de sessie en de sleutels op je eigen machine, doet het werk daar, en praat met het platform voor de onderdelen die geen geheim nodig hebben. Daarom documenteren deze pagina’s de lokale API, en daarom is ze geen tweede keus.