Prufy notes
A visual guide · about 235 minutes

How Prufy proves
you own a domain

Anyone can type apple.com into a form. Prufy gives you a unique code to publish in your domain's DNS, checks from several places that it's really there, keeps checking, and tells you when something changes. Nobody signs up. These notes show how, with diagrams you can step through and playgrounds that run the actual code from packages/core.

Start with the big pictureJump to the playground
Latest change · Nov 9, 2026
Soft edges on the landing page
The landing page now has a progressive blur along the top and bottom of the window and an oval vignette over the globe, after react.email's hero.
Step 1
Gathers evidence
packages/dns
Asks every server what it sees, and draws no conclusions.
Step 2
Judges it
packages/core
Pure functions. Evidence in, verdict out, no network needed.
Step 3
Remembers
packages/db
Stores the result so that no illegal state can ever be saved.

If you only remember one thing: dns gathers, core judges, db remembers.

Short on time?

These four chapters carry most of the understanding.

1
The big picture
What Prufy is for, its four parts, and the one idea that organizes them.
2
Life of a claim
One domain traced from a first visit to verified, with the database filling up as you go.
3
The verdict
The verification rule, and how every failure gets its own name.
4
The lifecycle
Seven statuses, eight events, and the only function allowed to move between them.

Orientation

The big picture
What Prufy is for, its four parts, and the one idea that organizes them.
Explore the system map6 min
Life of a claim
One domain traced from a first visit to verified, with the database filling up as you go.
Step through every move10 min

DNS

DNS in pictures
How a name becomes an answer, and why propagation is really about caches.
Scrub a cache timeline10 min
Asking DNS
Who the engine asks, what it asks them, and how it finds the right zone.
Walk a zone cut8 min
The verdict
The verification rule, and how every failure gets its own name.
Run the real classifier12 min

The domain

Turning input into a name
How a pasted URL, email or lookalike becomes one canonical domain, or a clear no.
Try any input7 min
The proof
What gets published in DNS, how the code is made, and why it isn't a secret.
Generate 128 bits7 min
The lifecycle
Seven statuses, eight events, and the only function allowed to move between them.
Drive the state machine12 min
What people see
How outcomes become one headline, one fix and one action.
Flip through every phase6 min

Types and data

Types that prevent bugs
The TypeScript techniques that turn runtime mistakes into compile errors.
Compare before and after10 min
The database
The tables, and the constraints that make illegal rows impossible.
Read the shape matrix10 min
Writing safely
How a status change and a takeover get written with no half-finished states.
Follow applyTransition7 min
Things happening at once
Races, frame by frame: locks, unique indexes and workers that skip each other.
Step through the races12 min

The app

The server
A request's path, the contract, the composition root and the background worker.
Swap production for tests9 min
Sessions without sign-up
One cookie, a hash in the database, and what each attribute of that cookie buys.
Make a token and its hash10 min
One-click setup
Domain Connect: what's built, what's missing, and why approval proves nothing.
Follow the handshake6 min
Setup links
A link as a capability: what whoever holds it can do, and what they deliberately can't.
Compare the two credentials7 min
Alerts
Six state changes send one. How it's decided, sent by email and push, and allowed to fail.
Run the real alert rule11 min
Trust and safety
Each way this could be attacked, and which layer stops it.
Open the threat map8 min
How it's tested
What each kind of test proves, and how to tell a test can actually fail.
See the test layers6 min

The interface

The page and its motion
A page that reads the phase and never decides it, one exception, and the motion rules.
Play the real presets12 min
The globe
How one fragment shader draws a sphere of dots with a wave crossing it.
Count the dots on a ring10 min
Installable, with push
The manifest, a service worker that caches nothing, and the iPhone limitation.
Step through the worker6 min

Make it stick

A real run
joycabinet.com, minute by minute, from your own audit log.
Replay it4 min
Decisions and tradeoffs
What each big choice bought, what it cost, and what would change it.
Weigh each one7 min
Check yourself
Scenario questions that show whether the ideas have landed.
Answer the scenarios10 min
Glossary
Every term, searchable.
Search any term3 min
Run it yourself
The commands, fixture domains and time travel to try everything for real.
Copy the commands5 min

As we build

What changed
Every change to the codebase, newest first: what it was, why, and where to read more.
Review the latest4 min

Where things stand

Core logic, DNS, database, API and UIBuilt, 864 tests
Renamed from Relay to PrufyDone, with a migration
Sessions without sign-upBuilt, one device
Alerts by email and pushBuilt, not yet received for real
Setup links for a helper or an agentBuilt
Landing page, claim page, setup pageBuilt
The globeWebGPU, with a still fallback
Installable, with pushBuilt, not tried on a phone
This workPR #13, open, not merged
GitHub ActionsPassed on PR #13
Deploys from GitHubOn merge, with previews
Running on real NodeDone, on Vercel
A real domain reaching verifiedDone before the rename
Concurrency on real PostgresTested with real locks
Signing in on a second deviceNot built
Rate limits in a shared storeNot built
One-click apply at a providerNeeds onboarding
The CLI in the heroMarked Soon