getplaid.direct

Le protocole, au grand jour.

Tout ce que fait getplaid.direct tient sur une page : donner un nom à ton serveur, l’aider à obtenir un certificat, rediriger un lien. Version 1.

Noms

Trois types de noms par serveur.

Le label, c’est le nom du serveur adapté au DNS, limité à 20 caractères, suivi de 6 caractères aléatoires. La partie aléatoire suffit à identifier le serveur.

NomTypePointe vers

<slug>-<id>.getplaid.directA / AAAAL’IP publique de ton serveur. C’est l’adresse qu’utilisent les amis.

<a-b-c-d>.<slug>-<id>.getplaid.directAUne adresse privée de ton réseau, pour que les écrans de la maison restent en local.

_acme-challenge.<slug>-<id>.getplaid.directTXTCréé par ton serveur le temps d’obtenir son certificat.

API HTTP

Sept appels, en JSON.

URL de base https://getplaid.direct/api/v1. Les erreurs reviennent sous forme d’un code et d’une phrase en anglais, avec un statut 4xx ou 5xx.

POST
/servers
Inscription. Renvoie l’id, un jeton secret affiché une seule fois, le nom d’hôte et le lien court. 5 par IP et par heure.
PUT
/servers/{id}
Mise à jour et signe de vie : au démarrage, toutes les 15 minutes et quand le port change.
DELETE
/servers/{id}
Désinscription. Les enregistrements disparaissent immédiatement.
PUT
/servers/{id}/acme-challenge
Publie les valeurs DNS-01 d’un certificat. Elles expirent au bout d’une heure.
DELETE
/servers/{id}/acme-challenge
Les efface.
POST
/servers/{id}/reachability
Vérifie depuis l’extérieur qu’un serveur PLAID répond. 10 par serveur et par heure.
GET
/ip
L’adresse que le service voit pour toi. Sans jeton.

POST /servers répond 201

{
  "id": "k3x7qa",
  "token": "…affiché une seule fois",
  "hostname": "living-room-k3x7qa.getplaid.direct",
  "url": "https://living-room-k3x7qa.getplaid.direct:32501",
  "shortUrl": "https://getplaid.direct/k3x7qa",
  "publicIp": "203.0.113.7",
  "port": 32501
}

Liens courts

Un seul lien à retenir.

Le lien que tu envoies

getplaid.direct/k3x7qa

Où il mène

living-room-k3x7qa.getplaid.direct:32501

Le service se contente de rediriger. Un ancien nom redirige toujours vers le nom actuel. Le port 443 n’apparaît pas dans l’adresse.

DNS

Le service répond pour getplaid.direct.

C’est le serveur DNS qui fait autorité sur la zone, pas un résolveur : les questions sur d’autres zones sont refusées, les noms inconnus reçoivent NXDOMAIN.

NomTypeRéponse

getplaid.directSOA, NSLe service lui-même

getplaid.directCAA0 issue "letsencrypt.org"

<label>A / AAAALa dernière IPv4 / IPv6 publique de ton serveur

<a-b-c-d>.<label>Aa.b.c.d, seulement pour les plages privées, CGNAT et link-local

_acme-challenge.<label>TXTLes valeurs DNS-01 en cours

Règles

Des règles sur lesquelles un serveur peut compter.

L’adresse vient de la requêteTon IP publique, c’est toujours celle d’où part l’appel. Personne ne peut faire pointer un nom vers une adresse qui n’est pas la sienne.
IPv4 et IPv6, chacune de son côtéUn appel ne met à jour que l’adresse de son propre type. Une adresse qui n’a pas été mise à jour depuis 24 heures n’est plus publiée.
Un jeton, un serveurAprès l’inscription, chaque appel porte un jeton. Un mauvais jeton et un id inconnu reçoivent la même erreur 401.
Des TTL courts60 secondes pour les enregistrements des serveurs, pour qu’une nouvelle IP soit vite prise en compte. Les serveurs sans nouvelles depuis 30 jours sont supprimés.
Les clés restent à la maisonChaque serveur obtient son propre certificat Let’s Encrypt via DNS-01. La clé privée ne quitte jamais ta machine.
Jamais de sondage en interneLa vérification d’accessibilité ne se connecte jamais à une adresse privée, CGNAT ou link-local.

Lire le document complet.

PROTOCOL.md est rangé à côté du code du service, et versionné avec lui.

Ouvrir sur GitHub