Vouch - IndieWeb

Vouch - IndieWeb
Jump to content
From IndieWeb
Vouch icon
This article is a
stub
You can help the IndieWeb wiki by
expanding it
with
relevant
information.
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
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 2026-04-24, 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.
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.
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 permalink
target
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 the
target
(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
and
target
valid URLs?
no: return
400
approve
source
no: return
400
does my site accept webmentions for
target
AND does
source
link to
target
no: return
400
200
accept webmention
Webmention with Vouch support:
start: receive webmention
are
source
and
target
(and
vouch
if present) valid URLs?
no: return
400
approve
source
no: has
vouch
param?
no: return
449
approve
vouch
no: return
400
does
vouch
link to
source
's domain?
no: 400
does my site accept webmentions for
target
AND does
source
link to
target
no: return
400
200
accept webmention
Webmention with Vouch support with async network traffic:
start: receive webmention
are
source
and
target
(and
vouch
if present) valid URLs?
no: return
400
approve
source
no: has
vouch
param?
no: return
449
approve
vouch
no: return
400
start async process to check webmention with vouch links
return
202
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 does
source
link to
target
no: status
400
is there a vouch to check?
no: status
200
accept webmention
does
vouch
link to
source
's domain?
no: status
400
status
200
accept webmention
Webmention with Vouch testing support (not in flow diagram) with async network traffic:
start: receive webmention
are
source
and
target
(and
vouch
if present) valid URLs?
no: return
400
has
vouch
param?
approve
vouch
no: return
400
approve
source
no: has
vouch
param?
no: return
449
or
warning: might not accept this unvouched in the near future.
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.:
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:
in reply to:
vouch:
received:
comment:
with publicly displayed "Vouched" text that links to a specific vouch URL.
vouch:
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:
in reply to:
vouch:
since Aaron has already linked to me, that URL is used
also sent:
in reply to:
third-party domain vouch:
simulating as if Aaron had
not
linked to me before
received:
as comment on:
vouch:
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
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
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
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
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:
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.
Can a vouch apply to shared membership
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
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:
(and following days).
This page is in progress documentation of that IRC braindump, with follow-ups.
Current log processing cursor:
Draw user flow, protocol flow diagrams, and relations between them (upload sketches)
Issues
Issues are hosted at
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
2019/SF/vouchnext
2019/Berlin/vouch
2018/vouch
2014/Cambridge/vouch
...
See Also
webmention
spam
earlier work on resolving vouch graphs
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
"Hi Ben, @t mentioned this tweet to me. I have a PHP library to convert h-event to iCal:
. It’s basic, but working well for my calendar page:
."
@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:
"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:
"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"
Retrieved from "
Categories
stubs
jargon