Knock docs

Reading the index…

One press. One human.

Knock lets your site let in a real person, once. They press green on their Wedgie, and your verifier checks that press against ENS and World Chain. You add a button and run one small service beside your site; nobody makes an account or types a thing.

Start the quickstartHow a knock works

  1. Your page calls knock() from a click.

  2. Knock's Door opens and asks the Wedgie, over USB.

  3. Its owner reads the site on the screen and presses green.

  4. Your verifier checks ENS, World Chain and the signature: one human, in once.

A knock: your page asks for one, Knock's Door opens and asks the Wedgie, its owner presses green, and your verifier checks the knock and lets one human in.
Markdown

Knock lets a site let in a real person, once, with no account, form or captcha. The person owns a Wedgie: a small USB device with a screen and two buttons, whose key is bound to their World ID on World Chain and named in ENS. When they knock on your site, the Wedgie shows your site's address, they press green, and your verifier checks what the Wedgie signed against ENS and World Chain.

You add two things to your site:

  • A Knock button, with @knock-dev/door-sdk. Its one function, knock(), opens Knock's Door and hands back what the Wedgie signed.
  • A verifier, which gives out challenges and checks each knock, eight checks in order: @knock-dev/verify inside your server, if it runs JavaScript, or knock-verifier, a small Rust service beside your site. If your server is in Rust, you can embed the same checks with the knock-verify crate instead.

What a knock tells you

A knock that passes your verifier tells you that, just now, on your site:

  • someone pressed green on a Wedgie whose key is in ENS under a name, such as wedgie.itzraj.eth;
  • the Wedgie signed your challenge, for your origin, with a counter higher than in any knock of its you've seen;
  • the name is switched on, so its owner hasn't revoked it or killed it;
  • that key is bound on World Chain to one human, proven with World ID;
  • if you asked, this human hasn't done this action on your site before.

It doesn't tell you who the person is. You get the Wedgie's name and the human's nullifier: a number that is the same for one human everywhere Knock is used, and that says nothing else about them. How a knock works goes through each step.

The parts

PartWhat it doesIn the repo
@knock-dev/door-sdkThe browser side. knock() opens the Door and resolves with the knock. One TypeScript file, no dependencies.packages/door-sdk
@knock-dev/verifyThe checks as a TypeScript package, for a server that runs JavaScript: Node, Bun, Deno, serverless.packages/verify
knock-verifierYour verifier: POST /challenge, POST /verify and GET /health, with SQLite for what's been used.server/verifier
knock-verifyThe checks themselves, as a Rust library, for your own server.crates/knock-verify
The DoorKnock's popup, at https://door.getknock.dev/knock. It talks to the Wedgie over USB, from the browser.apps/door
The Knock ConsoleWhere a person sets up their Wedgie, at https://getknock.dev: its name, its binding, and its records in ENS; and the kill switch. Sites never call it.apps/door
knockdRelays a Wedgie's binding to World Chain, and signs World ID requests, while a person sets it up. Sites never call it.server/knockd
@knock-dev/protocolThe messages a Wedgie signs (EIP-712), key helpers, and test vectors.packages/protocol
The Human ClubA demo site: petitions and fundraisers where each human signs once, checked with @knock-dev/verify.apps/bouncer

Every part is open source, in getknock/knock, and you can host any of them yourself.

Where Knock is today

Knock is new. Read this before you plan around it:

  • Nothing is on a registry yet. Every package is at 0.1.0: door-sdk and @knock-dev/verify aren't on npm, and knock-verify isn't on crates.io. The quickstart uses a checkout of getknock/knock.
  • Knocking needs a desktop Chromium browser, such as Chrome, Edge, Brave or Arc. The Door reaches the Wedgie over Web Serial, which Firefox, Safari and phones don't have.
  • Only one kind of binding counts: those made on KnockBinding v3's production deployment on World Chain. Bindings from World ID's Simulator (staging) never count.
  • One mode. Mode 1, Bound, takes the human from the Wedgie's binding. Mode 2, Fresh, a new World ID proof with each knock, isn't offered.
  • The nullifier is public. It sits in the name's ENS records, so two sites can tell that the same human knocked on both. Security says what follows from that.

Start here