API

Deux API

Deux choses différentes sont appelées API ici, et ce ne sont pas la même surface.

L’API locale appartient au compagnon de bureau, tcc. Le démon tourne sur ta propre machine et sert une interface HTTP sur l’adresse de boucle locale. Tout ce que tu peux faire dans le compagnon — vérifier trois mots, sceller un fichier, lister les connexions, gérer une organisation — a une route. Elle dispose d’un document OpenAPI versionné, à partir duquel ces pages sont écrites, et le démon sert ce même document aux appelants.

L’API de plateforme est le côté serveur : le service hébergé auquel parlent les applications. Elle n’est pas publiée, et ne porte aucune route propre à un utilisateur — voir ci-dessous, car la raison en est délibérée, pas une lacune.

Ce que couvre cette section

Ces pages couvrent uniquement l’API locale. Elles décrivent où écoute le démon, comment un appelant s’authentifie, à quoi ressemblent les réponses, et chacun des 79 chemins documentés.

Elles n’enseignent pas le compagnon lui-même. L’installer, s’y connecter et le faire tourner comme démon sont couverts dans les pages compagnon et ligne de commande.

Pourquoi l’API de plateforme est absente

La raison courte est qu’elle n’a aucun document publié, aucune version publiée et aucune promesse de stabilité, donc des pages à son sujet décriraient une surface envers laquelle personne ne s’est engagé.

La raison plus longue est celle qui ne changera pas : il n’existe aucune route propre à un utilisateur à publier sur la plateforme.

Répondre à « quel est le code de Mary ? » sur un serveur suppose que le serveur détienne le secret qui produit le code. Dès cet instant, la promesse de bout en bout n’est plus tenue — non pas parce que quelqu’un en abuserait, mais parce qu’elle cesse d’être vraie. Un serveur qui PEUT lire tes codes est un serveur dont la compromission lit les codes de tout le monde, et aucune précaution de notre part ne change ce qu’un attaquant emporterait.

Nous ne gardons donc aucun secret utilisateur sur aucun serveur que nous faisons tourner, et une API de plateforme orientée utilisateur est une chose que nous ne pouvons pas construire sans renoncer à cela. Ce que la plateforme expose est un travail de niveau système, machine à machine, qui ne touche aucun secret personnel, et un titulaire de compte n’y a de toute façon aucun accès.

Ce n’est pas une lacune en attente d’être comblée. Si l’API de plateforme est publiée un jour, elle couvrira le même terrain système et ne portera toujours rien qui t’appartienne.

La conséquence pour une intégration : la seule chose qui peut répondre à des questions sur les connexions d’un compte est quelque chose qui détient les clés de ce compte — le compagnon local. Il conserve la session et les clés sur ta propre machine, y effectue le travail, et parle à la plateforme pour les parties qui ne nécessitent aucun secret. C’est pourquoi ces pages documentent l’API locale, et pourquoi ce n’est pas un pis-aller.