Construire une app

Une app est un service HTTP que vous faites tourner, sur votre propre domaine, avec votre propre base de données. Spunto en connaît trois choses : une URL de base, un secret de signature que Spunto vous remet quand vous l’enregistrez, et le manifeste que l’app sert. Tout le reste — les tokens qu’elle obtient, les comptes qu’elle connecte, les machines qu’elle fait tourner — reste chez l’app.

Ce n’est pas une version simplifiée du fonctionnement des intégrations maison. GitHub (git), Google Cloud (runtime) et le runtime des machines que vous apportez sont des services séparés qui parlent exactement ce contrat ; rien sur cette page ne leur est réservé.

Les objets

Les installations appartiennent aux organisations, et c’est voulu : ce qu’une app produit — un credential de clone, une machine — appartient à l’organisation, et doit continuer de fonctionner quand la personne qui l’a connectée s’en va. Le grant est l’exception, pas la moitié du modèle.

Ce que votre app sert

Les appels signés portent un HMAC calculé sur la méthode, le chemin et le corps → Requêtes signées.

Le manifeste

GET /manifest

{
  "id": "acme-git",
  "name": "Acme Git",
  "description": "Repositories hosted on Acme Git.",
  "publisher": "Acme",
  "accent": "#2563eb",
  "auth": "oauth",
  "capabilities": [
    {
      "capability": "git",
      "operations": ["cloneCredential", "listRepos", "listBranches", "userCredential"]
    }
  ],
  "userGrantOperations": ["userCredential"],
  "publicUrl": "https://git.acme.dev/spunto",
  "installPath": "/oauth/install",
  "grantPath": "/oauth/user",
  "managePath": "/settings"
}

Spunto relit le manifeste toutes les minutes. Ajouter une opération à votre app, c’est déployer votre app — aucune release de Spunto, et les boutons qui en dépendent apparaissent d’eux-mêmes.

Les opérations optionnelles, c’est tout l’intérêt

Le dashboard affiche une fonctionnalité si et seulement si une app installée implémente l’opération qui la sous-tend. Un hébergeur git sans registerUserSshKey clone quand même — on ne propose simplement pas aux membres d’y enregistrer leur clé. Un runtime sans pause fait tourner des sandboxes quand même — le bouton Pause n’est simplement pas là. Déclarez ce que vous implémentez, rien de plus, et le produit s’adapte.

Installer en trois temps

Une redirection de navigateur n’authentifie personne. Les paramètres d’une installation ne sont donc jamais lus dans une query string : Spunto les signe, et confirme le résultat de serveur à serveur.

// POST /oauth/complete — signed
{ "orgId": "org_…", "userId": "usr_…", "completion": "c8f1…", "canInstall": true }
 
// 200
{ "result": { "kind": "install" } }   // or "grant"

C’est l’étape de confirmation qui rend inoffensif un lien transféré : un attaquant qui envoie son lien de lancement à quelqu’un d’autre ne peut pas rattacher le compte de cette personne à l’organisation de l’attaquant, puisque l’utilisateur avec lequel Spunto confirme est celui qui est vraiment connecté.

Un grant suit les mêmes quatre étapes, à partir de grantPath, avec un jeton de lancement dont le purpose vaut grant, et se valide pour ce seul membre.

Statut : Spunto demande, il ne sait pas

Spunto ne garde aucune copie de ce qu’une organisation a connecté. Pour afficher la page Integrations, il demande :

// POST /status — signed
{ "orgId": "org_…", "userId": "usr_…" }
 
// 200
{
  "result": {
    "installations": [
      {
        "externalId": "48213",
        "accountLogin": "acme",
        "accountType": "Organization",
        "accountAvatarUrl": "https://…",
        "installedAt": "2026-10-02T09:14:00Z"
      }
    ],
    "grant": { "present": false, "externalId": null }
  }
}

Renvoyez toujours grant, même si votre app n’a pas de grants — { "present": false, "externalId": null }. La déconnexion se fait dans votre app (sur votre managePath, par exemple) ; c’est par le /status suivant que Spunto l’apprend.

Appels de capability

Chaque opération est un POST signé, avec une seule enveloppe :

// POST /capabilities/git/cloneCredential — signed
{
  "orgId": "org_…",
  "userId": "usr_…",
  "input": { "repo": "acme/api", "repos": ["acme/web"] }
}

orgId dit quelle installation utiliser. userId est présent quand une personne est derrière l’appel, et c’est au nom de celle-ci qu’il faut agir pour une opération à grant. input est propre à l’opération — voir la référence de chaque capability.

Répondez par { "result": … } :

{ "result": { "scheme": "https-token", "username": "x-access-token", "token": "…", "expiresInSeconds": 3600 } }

Erreurs

N’importe quel statut hors 2xx, avec un corps JSON { "error": "…", "code": "…" }. Le message est montré au membre. Deux codes restent distincts jusqu’au dashboard, parce qu’ils ne demandent pas la même chose au membre :

Nos apps répondent aux deux par un 409 ; c’est le code qui compte. Tout le reste est signalé comme une défaillance de votre app.

Délais et nouvelles tentatives

Spunto attend une réponse pendant 10 secondes. L’appel lui-même n’est jamais rejoué : une seule implémentation répond, le résultat compte, et rejouer une requête à l’aveugle est la façon dont on crée deux exemplaires de quelque chose. Quand une capability réessaie bien — runtime.create, quand l’app était injoignable ou n’a pas répondu à temps —, elle le dit, et l’opération doit être idempotente sur l’id qu’on lui donne.

Un travail long (démarrer une machine, construire une image) ne tient pas en 10 secondes, et n’a pas à y tenir : répondez tout de suite avec un handle, et rendez compte de l’avancement par l’opération de statut que la capability définit.

Deux adresses

Spunto appelle votre app sur son URL de base — qui peut être privée, un nom sur un réseau interne. Les navigateurs la joignent sur publicUrl. Ce sont souvent les mêmes ; ce n’est pas obligatoire.

Publier une app

Ce que fige une revue

Le manifeste est toujours lu en direct : une app publiée peut donc gagner des opérations dans les capabilities pour lesquelles elle a été approuvée, sans que personne ne les revoie. Tout le reste reste tel que revu jusqu’à l’approbation d’une nouvelle version :

Pour changer l’un d’eux, Submit an update : la version publiée reste en place pendant que la nouvelle est revue. Pour essayer un changement avant de le soumettre, enregistrez une seconde app — acme-git-staging — et gardez celle qui est publiée pour ce qui a été revu.

Règles des apps publiées

• Seules les capabilities git et runtime sont ouvertes aux apps pour l’instant.
• Vos pages vivent sur votre propre origine : publicUrl est une URL https absolue, ou laissée de côté pour utiliser l’URL de base.
• Spunto n’appelle que des adresses publiques, et ne suit pas les redirections.
• Unlist retire une app publiée de la marketplace : les organisations qui l’utilisent la perdent aussitôt. Spunto peut aussi suspendre une app, ce qui la retire de toutes les organisations et refuse tout appel vers elle.

Les capabilities que vous pouvez implémenter

Le catalogue des capabilities appartient à la plateforme, et il est fermé : une app ne peut pas en inventer une, puisque rien ne l’appellerait jamais. Les harnais d’agent sont aussi des apps, mais tournent dans la plateforme — le flux d’une session est un chemin trop chaud pour passer par un proxy —, ils ne sont donc pas ouverts aux tiers.