Hash for Vouch

What is Hash for Vouch?

Hash for Vouch is a web service which demonstrates that the person sending a webmention probably isn't a spammer by requiring them to do a complex calculation.

If you prove that you're prepared to do a small amount of work, then Hash for Vouch will vouch for you when you send a webmention. This work basically means that sending a webmention will take you a few seconds longer; that isn't too onerous for you, but it is prohibitive for spammers who can't spam if sending webmentions takes a few seconds rather than thousands every second.

What are Webmentions? Vouch?

Webmentions are a simple way to notify any URL when you link to it on your site. Vouch is an anti-spam extension to Webmention; in particular, when one sends a webmention, one can also include a "vouch": a URL which links to your post and is trusted by the site you're mentioning, as evidence that you're worthy of trust.

What's the "work" that's done?

It's inspired by Hashcash, which is most famous as the bitcoin mining function. Basically, you take the source URL (where your webmention is coming from) and the time (an integer number of seconds since Jan 1st 1970 UTC), and a "nonce", such that sha256(source + "-" + time + "-" + nonce) begins with 5 zeroes. Doing this (that is: working out a nonce that fulfils the requirements) requires trying lots of different nonces, which takes time.

An example node.js implementation is in generaterequest.js in the source repo. An example Python implementation is:

url = "http://example.com"
t = int(time.time())
counter = 0
while 1:
    dig = hashlib.sha256("%s-%s-%s" % (url, t, counter)).hexdigest()
    if dig.startswith("00000"):
        print dig, counter
        print urllib.urlencode({"time": t, "nonce": counter, "source": url})
    counter += 1

Why do vouch pages disappear after some time, rather than live forever?

If they didn't, then a spammer could get a page vouched for, and then later change its content to contain spam and dynamically add links of pages they're webmentioning. This isn't peculiar to Hash for Vouch; it's a problem with Vouch generally, but with Vouch generally the receiver can decide that they no longer trust site X to vouch for anyone. I don't want people to treat Hash for Vouch in total as untrustworthy, so it goes to extra effort to avoid being used by spammers.

There are two reasons why vouch pages disappear. The first is that they are automatically deleted after 3 minutes even if they're not used. The second is that they are automatically deleted once they've been viewed 20 times. Both of these are to stop a spammer writing one page with a thousand URLs on, getting it vouched for (or getting a nice-looking page vouched for and then changing to list a thousand URLs you want to send spam to), and then sending a thousand spammy webmentions to those pages; once the first four have been sent and the recipient checks the vouch URL for validity, the vouch URL goes away. None of this should be a problem for people using Hash for Vouch correctly; that is, plan to send a webmention, get a vouch URL for it, send the webmention with the vouch URL attached, recipient checks the vouch URL, done.

That's not really what a "nonce" is, in cryptographic jargon

I know. But it's a convenient word, here.

What's the API?

Once you've calculated a nonce, POST to /endpoint with body source=http://yourpage.com/somepage&nonce=yournonce&time=1417359573. The time parameter must be an integral number of seconds, not a number of milliseconds. The API will return JSON, either {error: "Some error text"} or on success {url: "a vouch URL"}. If successful, you can use the vouch URL when posting your webmention; you should do so immediately, because vouch URLs disappear in time as described above.

Since a vouch URL will vanish once accessed 20 times, you can have Hash for Vouch vouch for a blog post containing 20 links and pass that same vouch URL to each of the 20 outgoing webmentions. If you want to use a Hash for Vouch vouch URL for more than 20 outgoing webmentions, you'll need to get two or more vouch URLs.

Who made this?

If you have questions, let sil know (or on Twitter at @sil).