Vouch
![Vouch icon](/images/thumb/9/9f/vouch.svg/128px-vouch.svg.png)
This article is a stub. You can help the IndieWeb wiki by expanding it.
The Vouch protocol is an anti-spam extension to Webmention that can also be used to customize how your site accepts responses from different audiences.
- See Vouch Proxy for the Single-Sign On OAuth client for Nginx to support IndieAuth.
Webmention with Vouch depends on understanding Webmention. Please read that first.
- Status
- This is a Living Specification yet mature enough to encourage implementations and feedback.
- Latest Published Version
- https://indieweb.org/Vouch
- Participate
- issues
- discussion on #indieweb-dev (on Libera IRC)
- Editors
- Aaron Parecki
- Tantek รelik
- Authors
- Other contributors: revision history
- License
- Per CC0, to the extent possible under law, the editor(s) and contributors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-09-01, the editor(s) and contributors (2015-04-07 onward) have made this specification available under the Open Web Foundation Agreement Version 1.0.
Summary
- If Bob is sending a webmention to Alice
- (who don't know each other, i.e. Alice has never linked to Bob),
- Bob sends along a third parameter, "vouch",
- where the vouch is a URL on Carol's site to a page that has a link to Bob's domain (thus "vouching" for Bob),
- and Carol's site is a domain that Alice approves of (e.g. has linked to in the past).
By doing so, Bob is telling Alice:
- please accept my webmention,
- because Carol,
- who you approve of,
- vouches for me.
Protocol
Webmentions are sent "from" a source URL "to" a target URL to notify the target that it has been mentioned at the source URL, with an optional "vouch" URL to help the target determine whether they should accept the webmention.
- Alice posts some interesting content on her site (which is set up to receive Webmentions).
- Bob sees this content and comments about it on his site, linking back to Alice's original post.
- Using Webmention, Bob's publishing software automatically notifies Alice's server that her post has been linked to by the URL of Bob's post by sending both his URL(source) and hers(target) to her.
- Alice does not know Bob...Alice has never linked to Bob. Bob sends along a third URL parameter called 'vouch'. Vouch is a URL belonging to Carol.
- Alice verifies that the source and target are valid URLs
- Alice checks if she approves Bob's domain. If she does, then Alice's publishing software verifies that Bob's post actually contains a mention of her post and then includes this information on her site, otherwise she rejects the webmention.
- If she does not approve of Bob's domain, Alice checks if she approves of Carol's domain.
- If she does, then Alice checks if the page provided has a link to Bob's domain.
- Finally, Alice's publishing software verifies that Bob's post actually contains a mention of her post and then includes this information on her site, otherwise she rejects the webmention.
If any checks fail, Alice's software returns 400.
Why
You should implement receiving Webmention with Vouch in order to automatically block all automated spam and to aid in moderation of mentions.
You should send webmentions with vouches to increase the chance that your webmention comments will be accepted, or approved from moderation in a faster manner. As more and more sites implement Webmention with Vouch, plain webmentions may be blocked more frequently or subject to more scrutiny.
How To
Vouch Selection
- The receiver posts a blog post on their blog
- The sender writes a post on their blog that links to the receiver's post.
- After publishing the post (i.e. it has a URL), the sender server notices this link as part of the publishing process and the server does Webmention discovery on the receiver's post to find its Webmention endpoint (if not found, process stops).
- The sender checks their own list of approved domains to see if the receiver is listed.
- If so, the sender proceeds to Sending with
vouch
set to an appropriate link. This could be a public list of approved domains, if the sender maintains one, or a previous post where they linked to the receiver.
- If so, the sender proceeds to Sending with
- The sender checks the receiver's site for a list of approved domains, or uses some other means to get a list of domains that the receiver has previously linked to.
- The sender checks if the receiver's list already contains their site.
- If so, the sender stores this link in their private list and proceed to Sending with
vouch
set to permalink to the page on receiver's site that contained this entry.
- If so, the sender stores this link in their private list and proceed to Sending with
- The sender compares the receiver's list to their own list of followers.
- If the sender finds a match between the lists, he proceeds to Sending using the URL stored with the match in their list as the
vouch
value. - If the sender has not found any relation, he proceeds to Sending without a
vouch
value.
Sending
- The sender's server sends a webmention to receiver's webmention endpoint with
source
set to sender's post's permalinktarget
set to receiver's post's permalink.vouch
(if any) set to permalink of a page that links to the sender's site, that the receiver will see as an acceptable source.
Receiving
- The receiver receives the webmention
- They verify that
target
(after following redirects) in the webmention is a valid permalink on that site (if not, processing stops) - The receiver's server verifies that the
source
(when retrieved, after following redirects) in the webmention contains a hyperlink to thetarget
(if not, processing stops) - The receiver's server checks for the existence of a
vouch
value. (if not, webmentions can be marked for moderation and processing stops or proceed to further spam filtering methods, etc) - The receiver's server checks that the base site of
vouch
is either his own site, or a site in his approved list. (if not, webmentions is marked for moderation and processing stops or proceeds to further spam filtering methods) - The receiver's server verifies that the vouch (when retrieved, after following redirects) contains a hyperlink to the domain used in source (if not, processing stops)
Flow Chart
Summary description of Webmention with vouch flowchart from 2014-285 IndieWebCamp Cambridge.
Webmention support only:
- start: receive webmention
- are
source
andtarget
valid URLs?- no: return
400
- no: return
- approve
source
?- no: return
400
- no: return
- does my site accept webmentions for
target
AND doessource
link totarget
?- no: return
400
- no: return
200
accept webmention
Webmention with Vouch support:
- start: receive webmention
- are
source
andtarget
(andvouch
if present) valid URLs?- no: return
400
- no: return
- approve
source
?- no: has
vouch
param?- no: return
449
- no: return
- approve
vouch
?- no: return
400
- no: return
- does
vouch
link tosource
's domain?- no: 400
- no: has
- does my site accept webmentions for
target
AND doessource
link totarget
?- no: return
400
- no: return
200
accept webmention
Webmention with Vouch support with async network traffic:
- start: receive webmention
- are
source
andtarget
(andvouch
if present) valid URLs?- no: return
400
- no: return
- approve
source
?- no: has
vouch
param?- no: return
449
- no: return
- approve
vouch
?- no: return
400
- no: return
- start async process to check webmention with vouch links
- return
202
- no: has
- start async process to check only webmention source and target links
- return
202
Async process to check webmention links:
- does my site accept webmentions for
target
AND doessource
link totarget
?- no: status
400
- no: status
- is there a vouch to check?
- no: status
200
accept webmention
- no: status
- does
vouch
link tosource
's domain?- no: status
400
- no: status
- status
200
accept webmention
Webmention with Vouch testing support (not in flow diagram) with async network traffic:
- start: receive webmention
- are
source
andtarget
(andvouch
if present) valid URLs?- no: return
400
- no: return
- has
vouch
param?- approve
vouch
?- no: return
400
- no: return
- approve
- approve
source
?- no: has
vouch
param?- no: return
449
or- warning: might not accept this unvouched in the near future.
- no: return
- no: has
- start async process to check webmention with vouch links
- return
202
IndieWeb Examples
IndieWeb Examples of receiving and sending Webmention with Vouch, in order of implementation.
Aaron Parecki
Aaron Parecki's previous version of p3k supported receiving Webmention with Vouch testing (unvouched warning option) on aaronparecki.com since 2014-10-17. E.g.:
- http://aaronparecki.com/replies/2014/10/17/1/vouch has a comment from Ben Roberts with publicly displayed "(vouched for by waterpigs.co.uk)" text where the waterpigs.co.uk text links to a specific vouch URL.
Ben Roberts
Ben Roberts uses Postly on ben.thatmustbe.me to support sending and receiving Webmention with Vouch as of 2014-10-17. E.g.:
- sent: https://ben.thatmustbe.me/note/2014/10/17/5/
- received: https://ben.thatmustbe.me/post/2014/10/16/1/totp_and_you
- comment: https://kylewm.com/reply/2014/10/17/1/this-explanation-makes-me-think-totp with publicly displayed "Vouched" text that links to a specific vouch URL.
- vouch: https://kartikprabhu.com/notes/steel-countertop-kylewm
- Implementation details for sending a vouch: Postly#Searching_for_a_domain_to_use_for_a_vouch
gRegor Morrill
gRegor Morrill uses ProcessWire on gregorlove.com to support sending and receiving Webmention with Vouch as of 2015-11-29.
- sent: http://gregorlove.com/2015/11/testing-webmention-with-vouch-fingers/
- in reply to: http://aaronparecki.com/notes/2014/10/17/1/p3k
- vouch: http://aaronparecki.com/events/2014/06/28/1/indiewebcamp-2014
- since Aaron has already linked to me, that URL is used
- also sent: http://gregorlove.com/2015/11/another-webmention-with-vouch-test/
- in reply to: http://aaronparecki.com/notes/2014/10/17/1/p3k
- third-party domain vouch: https://indieweb.org/irc-people
- simulating as if Aaron had not linked to me before
- received: https://ben.thatmustbe.me/note/2015/11/30/1/
- as comment on: https://gregorlove.com/2015/11/testing-webmention-with-vouch-fingers/
- vouch: https://indieweb.org/irc-people
- Received vouch is not displayed publicly yet.
Martijn van der Ven
Martijn van der Ven supports receiving Webmentions with Vouch on his endpoint, and does rudimentary checking of the validity.
- It flagged a Webmention received from
gRegor Morrill as invalid because GitHub was set as a vouch. Anyone could have created a page on GitHub to create a โfakeโ vouch for themselves, so I block such silos.
Design Considerations
Easy For Receiver Implementation
In general a key goal with "vouch" is something that is easy for the receiver to process, and instead put more burden on the sender.
Shift Burden To Sender
Typical protocols susceptible to (abused by, made nearly useless by) spam (e.g. SMTP, Pingback, Trackback) make it very easy for the sender to send, and thus put all the burden of dealing with filtering undesired senders on the receiver.
Vouch pushes the (potentially cognitively challenging) work of 2nd degree discovery onto the sender of the webmention, and instead makes it easy for the receiver to implement.
Zero moderation
Another key goal is to build a system with zero moderation tax, at least to deal with automated spam systems.
Which pages to trust?
A few ideas of how to build a list of pages that you accept as Vouch links. These could have different priorities or levels of trust, with different consequences.
- pages you follow
- pages of people you explicitly trust (friends)
- event-pages for events you have attended (maybe doesn't scale for large events, but e.g. visiting an IndieWebCamp likely means I'd want to see responses from other attendees)
- members of a web ring
- your own site
FAQ
(in progress)
Is vouch saying you know me from
Q: Is a vouch saying "you may know me fromโฆ" ?
A: Not quite. No assertion of "may" nor "know". Just a "here's someone's {C} (perma)link, you {B} have linked to {some URL at C's personal domain}, where {C} links to me {some URL at A's personal domain}"
Do I vouch for my friends
Q: Do I vouch for my friends?
A: No, no assertion of friendship is implied or used by vouch.
What is HTTP 449
Q: What is the HTTP 449 status code?
A: HTTP 449 is a status code used by Microsoft to mean "Retry With"[1]
Why not HTTP 401
Q: Why not use the HTTP 401 status code?
A: HTTP 401 requires that the response include a "WWW-Authenticate" header, and says that the client can retry the request with authentication. Since Vouch does not involve authentication of any kind, this is not an appropriate response code to use.
Why not HTTP 403
Q: Why not use the HTTP 403 status code?
A: While there may be future uses of 403 in Vouch, currently the meanings of 403 do not map to anything in vouch.
From https://en.wikipedia.org/wiki/HTTP_403
A 403 response generally indicates one of two conditions:
- Authentication was provided, but the authenticated user is not permitted to perform the requested operation.
- The operation is forbidden to all users. For example, requests for a directory listing return code 403 when directory listing has been disabled.
Vouch is not about authentication, thus the first makes no sense. Nor would vouch be indicating that an operation is forbidden to all users, thus the second does not apply either.
- Alternatively from
Ben Roberts
From http://tools.ietf.org/html/rfc7231#section-6.5.3
The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it. A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any). If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials. However, a request might be forbidden for reasons unrelated to the credentials.
While this could work for this purpose, 403 implies that the server will not take any action. There is no actual requirement that webmentions that are not vouched be dismissed. It is perfectly acceptable to put unvouched webmentions in to a moderation queue for example. The response only indicates that it would be better to reply with vouch.
How can a sender find a vouch link
Q: How can the sender find such a vouch link?
A: How do people in general explain how they know each other? We can push this question off to arbitrary social sidebands of choice, the way people share links informally in all sorts of ways.
In addition, since such social questions are of interest beyond commenting (as evidence by Facebook and other silos showing how many friends in common you have and who they are), there's likely to be one or more aggregators that surface this information in some queryable way.
If Alice is already a reader of Bob's content (which Alice should be, since she is sending them a comment on one of Bob's permalinks), then Alice should already be somewhat familiar with who Bob links to (or can quickly check Bob's home page or recent posts for people). Alice should also be relatively familiar with who links to her own site (hint: Alice's recent incoming webmentions, or recent HTTP referers [sic]).
Thus with a quick look at Bob's home page (or recent posts) Alice should be able to trivially recognize "there's someone (Carol) that sent Alice a webmention recently," and go pull that out of Alice's queue/history of recent webmentions, and use that as a vouch URL.
Someone might also setup a service like say socialsearchme.com where you can put in your personal site, and see who has linked to you (most recently, most frequently), who you've linked to, the overlap, as well as how many and who you have in common.
In which case, as a user (Alice), after commenting (and presumably having their "normal" webmention rejected), they could check a hypothetical service like socialsearchme.com for themselves, see that they'd linked to Bob, and then see how many (if any) people they have in common, especially, if there are any people that Bob has linked to that link to Alice, and if so, presto, that's a "vouch" URL.
This manual human step of checking, i.e. "Hey how do we know each other" adds to the strength of the social tie between the commenter and the post author.
How do I verify a vouch
Q: How do I know if the vouch I received is legit. i.e. do I have to verify that there is a link between sender and voucher?
A: As the receiver, you have to do two (relatively) simple checks.
First, regarding: "don't I have to verify that there is a link between sender and voucher" - in one direction only, that vouch URL links to sender's personal domain. That's the easy check.
The second, potentially more challenging check, is you have to verify that you approve the vouch's site/domain (e.g. perhaps a link from your blogroll, or a whitelist, or your Twitter followings, nicknames cache, outbound link cache (i.e. a cache of every domain you've linked to), etc. take your pick).
Must I trust voucher knows source
Q: But can anyone can send me a webmention with voucher = someone that I've linked to, should I just trust that they know the source?
A: No notion of "trust" needed. Just links. You MUST verify that the vouch (presumably a permalink at the vouch's site) links to the source's site.
Continued: "or do I go fishing in your friendslist to verify it?" No. There is no need to crawl anywhere from the vouch URL.
Why does Twitter not worry
Q: Why don't people worry about this for Twitter?"
A: They do. :) See Twitter silo mentions of Tantek รelik's Twitter profile: https://twitter.com/search?f=realtime&q=%40t&src=typd with plenty of spam.
Must I always send a vouch
Q: If I want to send a webmention to a colleague for the first time, I have to somehow...
A: Not necessarily. The Vouch protocol is a backwards compatible extension to Webmention. E.g.:
- You send a webmention as if you would today.
- Perhaps the receiver is already a fan of yours (secretly, in their private whitelist, nicknames cache, etc.) and thus your webmention is accepted without any additional work.
Q: Can a vouch can apply to a shared membership too? E.g. chat-names or next-hwc, or XOXO?
A: A vouch URL could be for example User:Kevinmarks.com, which obviously links to the domain(s) (known.)kevinmarks.com, and thus vouches for any permalinks at those domains. Then the receiver of the webmention has to decide, do I approve of indieweb.org (e.g. have linked to it before, likely yes), ok I'll accept that site as a vouch, and the specific vouch URL, and thus the webmention.
Is the vouch a sponsor
Q: Is the vouch is a sponsor?
A: No, the vouch is not a "sponsor" or any other new term. The vouch (C) is just a (perma)link, which directly links to A's domain, and which B is likely to approve (e.g. has linked to C's domain previously).
Does vouch make all webmentions manual
Q: Does vouch make the whole webmention sending manual? No auto-sending webmentions?
A: It does not. For example it is likely your code can programmatically itself test http://indieweb.org/irc-people and use it as a default vouch.
From there, you can decide how much intermediate UI you want to show, "The comment you sent is awaiting some form of vouching that they link to that links to you" with a URL field to enter. Plenty of opportunity to crawl, cache, innovate there.
Does vouch make it too hard to send webmentions
Q: Does this make it too much work to send webmentions?
A: Maybe. We won't know until we attempt to implement Webmention with Vouch and see what roadblocks we run into.
When do I know to send a Vouch with a Webmention
Q: When's a 'good' time to send a Vouch with a Webmention?
A (from Jacky Alcinรฉ on 2021-03-31 10:19 PST): It'd be ideal to do so if the Webmention endpoint explicitly asks to. If the Webmention is capable of determining prior success rates, it can omit them in that case. But if it's one to be very 'friendly' (like to ask first), then sending a Vouch to a very public page (like chat-names) could help coax a endpoint to trust them (keeping bad actors on the Wiki would be ideally hard to do).
How can I use Vouch with backfeed from silos
We recommend that you don't. Vouch is promising for native IndieWeb moderation, but it expects each user has their own domain, which generally isn't true on silos. Also, quality and behavior of users, posts, comments, moderation, etc on silos varies significantly from IndieWeb sites, and across different silos themselves. If you want to programmatically filter backfeed webmentions, we recommend special casing backfeed senders like Bridgy based on source URL domain, or individual silos or even individual silo users based on u-url
domain and path.
Also see backfeed#Moderation_and_spam
In Progress
Vouch was braindumped into IRC: http://indieweb.org/irc/2014-09-28 (and following days).
This page is in progress documentation of that IRC braindump, with follow-ups.
- Current log processing cursor: http://indieweb.org/irc/2014-09-28#t1411947675795
- Draw user flow, protocol flow diagrams, and relations between them (upload sketches)
Issues
Issues are hosted at https://github.com/indieweb/vouch/issues
to do
To be written up here in this wiki page from that braindump
- clean up vouch protocol flow summary
- vouch protocol flow details
- vouch FAQ
To be drawn and posted:
- vouch user-flow diagram
- vouch protocol-flow diagram
Sessions
See Also
- webmention
- spam
- earlier work on resolving vouch graphs http://www.levien.com/free/tmetric-HOWTO.html
- 2018-04-27 Fast Company: Say Goodbye To The Information Age: Itโs All About Reputation Now
- An example of a manual "vouch" post on Twitter https://twitter.com/gRegorLove/status/1007376630476607489
- "Hi Ben, @t mentioned this tweet to me. I have a PHP library to convert h-event to iCal: https://github.com/gRegorLove/mf2-to-iCalendar. Itโs basic, but working well for my calendar page: https://gregorlove.com/calendar." @gRegorLove June 14, 2018
- 2014/Cambridge/vouch was a session at Cambridge 2014
- 2018/vouch was a session at IWS 2018
- 2018-07-01
David Shanske Brainstorming on Implementing Vouch, Following and Blogrolls
- What can Webmention learn from Email, a session at IWC concerned with how email spam systems may apply to webmentions
- Succinct problem statement: https://twitter.com/marcoarment/status/1125543048950185984
- "Your instincts are correct. I never want to create a venue that can be used to harass people or spread hate or abuse. Any public commenting system requires constant moderation to avoid that, and I neither have nor want the resources to run that kind of moderation." @marcoarment May 6, 2019
- Lurking and Social Networks -- the network topology stuff is particularly relevant to things like how to find, use, verify Vouch links, and what kind of Vouch ties a blogging/commenting tool should look for
- Why: https://twitter.com/fvsch/status/1148159831087419392 https://twitter.com/WalterStephanie/status/1148160270856065024
- "I see a few people on the Indie Web movement adding Webmentions to their blogs and I'm wondering: it looks like they're all men? What happens _when_ (not if) you have thousands of webmentions that are 95% abuse and threats from white/male supremacists?" @fvsch July 8, 2019
- Vouch Proxy
- primary use-case: a way to allow comments from people who know you but you don't know them to automatically show up on your website by saying "hey you know me through this person" AKA the friend's friend house party protocol. "Who do you know here?" "I'm friends with so-and-so" "Oh ok I trust them and their choice of friends, come on in"