Connect a site

Connect gives your site its naulon credential without anyone copying a key. Your site asks naulon for one, you approve it on naulon.app, and naulon hands it straight back to your site. Approving also proves you own the domain, so there is no separate verification step.

It works the same way for WordPress, for a Node or Python app, and from a terminal on the server your site runs on.

WordPress

1. Install and activate the plugin: Plugins → Add New, search for naulon, then Install Now and Activate.
2. Open naulon → Setup in the WordPress admin sidebar and choose Connect to naulon.
3. Sign in to naulon.app if you are not already. You see your site's address and the name the plugin gave it.
4. Choose which of your naulon sites this is, or let naulon create one, then Approve.
5. You land back on the Setup screen with a notice saying the site is connected. Step 2, proving the domain, is already ticked.

Then switch the toll on in step 4 of Setup.

Your site must be served over https at the address WordPress itself uses, with its admin on that same address. naulon checks your site before it shows Approve, and it can only reach a site that answers on its public https address.

Authors on a connected WordPress site

A connected site's credential can quote and settle tolls for that site and nothing else. It cannot send email on your behalf. So when an author asks to be paid and you choose Approve on naulon under naulon → People, naulon.app opens with that author's email and payee id already filled in, for that site. Check them and choose Send invite. Nothing is sent until you do.

Node

import express from "express";
import { naulonConnect, naulonNode, naulonSite } from "@naulon/enforce";

const connect = naulonConnect({ clientName: "My blog", site: "https://blog.example.com" });
const app = express();

app.use(naulonNode(naulonSite({ connect })));

app.post("/admin/naulon/connect", async (_req, res) => {
  const r = await connect.start({ site: "https://blog.example.com" });
  r.ok ? res.redirect(303, r.url) : res.status(400).send(r.error);
});

app.get("/naulon/connect/return", async (req, res) => {
  const r = await connect.finish(new URL(req.url, "https://blog.example.com").searchParams);
  // Store r.credential as a secret, as NAULON_KEY.
  res.send(r.ok ? "Connected." : r.message);
});

Mount the middleware before anything that answers /.well-known/: naulon fetches two paths there before it shows Approve, and they must answer whether or not your site is tolled yet. A site served by several processes passes a ConnectStore backed by its database, so the process naulon asks is not required to be the one that started the connect.

Python

from naulon.connect import Connect

connect = Connect(client_name="My blog", site="https://blog.example.com")

started = connect.start("https://blog.example.com")
# Redirect the owner to started.url.

done = connect.finish(request.GET)
# Store done.credential as a secret, as NAULON_KEY.

Pass the same Connect to the middleware so the two paths are answered: NaulonWSGI(app, connect=connect), or NAULON["CONNECT"] as a dotted path in Django.

From a terminal

A site with no settings page can connect from the server it runs on. With the middleware mounted and the app running, in the app's directory:

npx naulon connect --site https://blog.example.com

It prints an address to open on any device, your phone included. The app finishes the connect itself and keeps the credential in .naulon/credential. Add .naulon/ to your .gitignore.

What approving proves, and for how long

Your site answers a proof only it can compute from its credential, at /.well-known/naulon-challenge/. naulon fetches it through your domain's own DNS when you approve, and again from time to time afterwards. That is what keeps the domain yours on naulon.

If your site stops answering it, for example because the domain moved to someone else or the plugin was removed, the domain stops being verified for your account. Connect again from the same place to restore it.

Revoking

Every connected site appears in Settings → API & webhooks, named after its address. Revoke it there. Agents then read your site free until you connect again. In WordPress, Disconnect on the Setup screen does the same from the site's side.

When it does not work

"… does not offer Connect": the gate address in your settings does not answer Connect. Check it is https://gate.naulon.app, or the address of the gate you run. You can paste a key instead under Paste a key on the Setup screen.

"… could not be reached": your server cannot make outgoing https requests to naulon. A firewall or a host that blocks outbound traffic is the usual cause.

naulon says it cannot reach your site: naulon fetches your site before it shows Approve. A site behind a login, on http, or only reachable inside your network cannot be checked.