tk-link — tktk.link ===================== The backbone is a reverse tunnel: backend services open persistent outbound connections to the backbone and have client connections handed to them through one. Clients reach a service at .tktk.link. Everything authenticates with a TLS 1.3 CLIENT CERTIFICATE. You generate a keypair, self-sign it, and register the public half; the private key never leaves your machine and the backbone stores nothing that could be leaked or replayed. There is no bearer string, no header to copy, no signed URL. THREE HOSTNAMES, because a certificate is demanded during the HANDSHAKE and that decision is made per SNI name, before any request exists. Every path is served on exactly one of them; the wrong host answers 421, never a redirect. api.tktk.link THE API. Everything programmatic except registration: the management calls below (client certificate) and the admin calls (Bearer token). The handshake asks for a certificate and lets you decline — declining is how the admin token works — so a call that needs to know who you are and got no certificate answers 401. provision.tktk.link REGISTRATION, and nothing else. The one place a machine with no registered key can be heard: it accepts a certificate the backbone has never seen, where every other name refuses an unknown key inside the handshake, before HTTP exists. Nothing reachable here grants anything, which is why it is a name of its own. tktk.link The console, for humans in a browser. NO certificate is requested at all — a browser prompted for one is a dead end. Sign-in, `/healthz` and this page live here; `/v1/*` does not. ── 0. GET AN IDENTITY (once) ─────────────────────────────────────────────── 1. Generate a keypair and self-sign a certificate. Compute the fingerprint the backbone keys you on: openssl x509 -in cert.pem -pubkey -noout \ | openssl pkey -pubin -outform DER \ | openssl dgst -sha256 2. Ask a human to recognise it — CONNECTING WITH THAT CERTIFICATE: curl --cert cert.pem --key key.pem \ -X POST https://provision.tktk.link/v1/principals/requests \ -d '{"name": "laptop"}' There is no key in the body and none is read from one: the fingerprint registered is the one taken off this TLS connection. Completing the handshake signs it with your private key, so it proves possession — whereas a public key in a request body proves nothing, and could be anyone's. Connect without a certificate and you are told to bring one. Response: an authorize_url, a short user_code, and a poll_secret. 3. Show the user_code, then hold a long poll open: GET https://provision.tktk.link/v1/principals/requests/ x-principal-request-secret: {"status": "pending"} means "reconnect immediately". On approval you get {"status": "approved", "principal": {...}} — your principal UUID and the NAMESPACE you own. Nothing in that response is a secret. Open the authorize_url while signed in, check the code matches, approve. The principal is owned by whoever approves it: it appears in their console and they can revoke it. On an embedded device whose OWN browser opens that link, append ?embedded=1: the approval page then closes its tab on success instead of linking to a console the device cannot use. Best-effort — a normal desktop tab ignores the scripted close and just shows a "you can close this tab" button. ── 0a. SUB-IDENTITIES (optional, no server involvement) ──────────────────── Your certificate can act as its own CA. Issue short-lived leaf certificates whose Common Name is