Skip to content

How Muppy Builtin DNS is built, and why

Muppy Builtin DNS (MBD) is a DNS API for two uses, and only two:

  • the DNS-01 challenge of ACME, so that a customer's infrastructure gets its certificates;
  • Custom Domains: a customer's own name declared in front of one of their public names (Cloudflare for SaaS today).

Setting it up is described in Muppy Builtin DNS. This page explains its shape.

Three zones, two flows

 customer's infrastructure        customer's Muppy               MBD Server
 Traefik (Lego httpreq)  ─flow 1─▶ MBD Client domain  ─flow 2─▶  a Muppy instance ──▶ DNS provider
 cert-manager (webhook)            (HTTPRequest API)             (muppy.io)            of its backend
  • Flow 1 stays inside the customer's infrastructure. Traefik and cert-manager talk only to the customer's own Muppy, through its HTTPRequest API, with a credential that belongs to the MBD Client domain. They never talk to the MBD Server.
  • Flow 2 goes from Muppy to Muppy. Only the customer's Muppy talks to the MBD Server, over the MBD protocol, each request signed with AWS SigV4.
  • Nothing else crosses. The customer's infrastructure never reaches the MBD Server, an MBD key never leaves the customer's Muppy, and the MBD Server never calls the customer's Muppy.

Who does what

Does Never does
The customer's Muppy (MBD Client domain) acts as the gateway of its infrastructure: checks flow 1's credential and that the name is under its domain, then relays over the MBD protocol hand its MBD keys to its infrastructure
The MBD Server checks the signature, allows the key on its served name, applies its quotas and its status, writes through its backend domain; declares Custom Domains at the backend's provider expose its backend, or talk to a customer's infrastructure
The backend domain holds the records, at its DNS provider (OVH, or Cloudflare with Advanced Certificate Manager) —

Why it is built this way

  • A subdomain without the zone. A provider key opens a whole zone, often a whole account. A customer needs to write under its own name and nowhere else. MBD gives it that name; the provider keys stay with the server.
  • The server stays in control. It can suspend a customer and cap its records and Custom Domains without touching the provider or the other customers.
  • One protocol in front of several providers. The customer does not know whether the backend is OVH or Cloudflare; changing the backend changes nothing on its side.
  • Each frontier has its own credential. The customer's infrastructure holds only a credential for its own domain, valid at its own Muppy. A compromised Traefik reaches neither the MBD Server nor another customer's domain, and the MBD Server talks to one kind of caller only: a customer's Muppy.
  • SigV4 between Muppy instances: the secret never travels. Only a signature does, bound to the request and to its time; the server refuses a signature older than 15 minutes. Capturing a request gives neither the secret nor a way to forge another one. Sent over plain http://, a key is treated as compromised at its first use.
  • The customer's Muppy is the gateway because it already knows and runs that infrastructure: it holds the only MBD key, and gives its infrastructure a local credential instead.

The protocol

  • Records: /mpy/dns/v1/records, with POST, GET, PUT and DELETE. Custom Domains: /mpy/dns/v1/custom-hostnames.
  • Listing the records proves everything at once — the signature, the right to the domain, an active domain — and returns when the key expires.
  • A failure answers {"status": "error", "error": "…"}; GET also carries it in its HTTP status. A backend that is unavailable answers Backend unavailable: ….

Custom Domains cost the server. Its provider bills each declared name; the server's quota of Custom Domains caps it, and some charges may apply.

Sunray lets the MBD API through. An MBD Server's Muppy usually sits behind Sunray, whose default rule allows the MBD API: keep that rule when you set up the server.

The details, with the signed examples, are in Muppy Builtin DNS.