ENFR
Install
Install

getplaid.direct

The protocol, in the open.

Everything getplaid.direct does fits on one page: give your server a name, help it get a certificate, redirect one link. Version 1.

Names

Three kinds of names, one per server.

The label is the server name made safe for DNS, cut to 20 characters, plus 6 random characters. The random part alone identifies the server.

NameTypePoints to
<slug>-<id>.getplaid.directA / AAAAYour server’s public IP. This is the address friends use.
<a-b-c-d>.<slug>-<id>.getplaid.directAA private address on your network, so screens at home stay at home.
_acme-challenge.<slug>-<id>.getplaid.directTXTSet by your server while it gets its own certificate.

HTTP API

Seven calls, JSON in and out.

Base URL https://getplaid.direct/api/v1. Errors come back as a code and an English sentence, with a 4xx or 5xx status.

  • POST
    /servers

    Register. Returns the id, a secret token shown once, the hostname and the short link. 5 per IP per hour.

  • PUT
    /servers/{id}

    Update and heartbeat: at startup, every 15 minutes, and when the port changes.

  • DELETE
    /servers/{id}

    Unregister. Records disappear at once.

  • PUT
    /servers/{id}/acme-challenge

    Set the DNS-01 values for a certificate. They expire after 1 hour.

  • DELETE
    /servers/{id}/acme-challenge

    Clear them.

  • POST
    /servers/{id}/reachability

    Check from outside that a PLAID server answers. 10 per server per hour.

  • GET
    /ip

    The address the service sees for you. No token needed.

POST /servers answers 201

{
  "id": "k3x7qa",
  "token": "…shown only once",
  "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
}

Short links

One link to remember.

The link you send

getplaid.direct/k3x7qa

Where it lands

living-room-k3x7qa.getplaid.direct:32501

The redirect is all the service does. An old name still redirects, to the current one. Port 443 is left out of the address.

DNS

The service answers for getplaid.direct.

It is the zone’s authoritative name server, not a resolver: questions about other zones are refused, unknown names are NXDOMAIN.

NameTypeAnswer
getplaid.directSOA, NSThe service itself
getplaid.directCAA0 issue "letsencrypt.org"
<label>A / AAAAYour server’s last public IPv4 / IPv6
<a-b-c-d>.<label>Aa.b.c.d, only for private, CGNAT and link-local ranges
_acme-challenge.<label>TXTThe current DNS-01 values

Rules

Details a server can rely on.

The address is the request’s

Your public IP is always the source of the call. Nobody can point a name at an address they don’t own.

IPv4 and IPv6 apart

A call refreshes only its own family. An address not refreshed for 24 hours stops being published.

One token, one server

Every call after registering carries a bearer token. A wrong token and an unknown id get the same 401.

Short TTLs

60 seconds for server records, so a new home IP spreads fast. Servers silent for 30 days are removed.

Keys stay home

Each server gets its own Let’s Encrypt certificate through DNS-01. The private key never leaves your machine.

No probing inside

The reachability check never connects to a private, CGNAT or link-local address.

Read the whole document.

PROTOCOL.md lives next to the service’s code, versioned with it.

Open on GitHub