A Node.js webmention verifier
npm install webmention-verifier
Webmention Verifier will mostly verify webmentions per the W3c specification. Mostly.
const wmverifier = require('webmention-verifier');
module.exports = async function () {
const webmention = await wmverifier(source, target[, acceptableHosts]);
}
It will:
- ✅ Verify that
source
andtarget
are valid URLs (must) - ✅ Reject the request if
source
andtarget
are not the same URL (must) - ✅ Perform a
GET
request onsource
and confirmsource
mentionstarget
(must) - ✅ Handle arbitrary microformats (IE
<a class="u-arbitrary" href="http://your-site.com">
) - ✅ Handle sources with no microformats (added in v1.1)
It can:
- ✅ Check if receiver is a valid resource to accept webmentions for
target
(should)
It wont:
- ❌ Process the request asynchronously (more below) (should)
- ❌ Limit the number of redirects during the
GET
request onsource
(should) - ❌ Store the webmention anywhere
- ❌ Check
source
against a blocklist (I will add this at some point)
source
: (String) URL of the source of the webmentiontarget
: (String) URL of the target of the webmentionacceptableHosts
: (Array of strings, optional) domains that are accepted by this webmention receiver. Should not include protocols (https://
). Example:['www.timculverhouse.com', 'timculverhouse.com', 'sub-domain.domain.tld']
Returns an object with properties:
statusCode
: (Numeric) 400 for rejected webmentions, 200 for verified webmentionsbody
: (String) Description of the status codewebmention
: (False || Object) False if rejected, otherwise a JF2 object (see below)
The webmention will be a JF2 object, which will have all discovered microformat properties, as well as:
wm-source
: Equal tosource
wm-target
: Equal totarget
wm-property
: Equal to the type of webmention ("in-reply-to","like-of","arbitrary-value")wm-verified
: The date-time the webmention was verified
This verifier does all it's check synchronously. This is not recommended by the spec, but it is not capable of knowing how to form a location URL for you to respond to the sender with. So it doesn't do that.
It would be possible to add an option to have the verifier respond in an async matter (do what it can without fetching, respond with a code, and you handle the location URL crafting on your end while it finishes up verification);.
HTML (source
= https://www.example.com/post.html, target
= "https://www.duckduckgo.com"):
<html>
<head>
<title>Single h-Entry</title>
</head>
<body>
<article class="h-entry">
<h1 class="p-name">Article Title</h1>
<section class="e-content">
<a href="https://www.duckduckgo.com" class="u-in-reply-to">DuckDuckgo</a>
This is some content
</section>
</article>
<a href="https://www.example.com/virginia-woolf.html" rel="author">about Virginia Woolf</a>
</body>
</html>
Javascript:
const wmverifier = require('webmention-verifier');
module.exports = async function() {
const res = await wmverifier('https://www.example.com/some-post', 'https://www.duckduckgo.com');
console.log(res);
}
/* Output
{
statusCode: 200,
body: 'Webmention verified',
webmention: {
type: 'entry',
name: 'Article Title',
content: {
html: '\n' +
' <a href="https://www.duckduckgo.com" class="u-in-reply-to">DuckDuckgo</a>\n' +
' This is some content\n' +
' ',
text: 'DuckDuckgo\n This is some content'
},
'in-reply-to': 'https://www.duckduckgo.com',
'wm-property': 'in-reply-to',
'wm-target': 'https://www.duckduckgo.com',
'wm-source': 'https://www.example.com/post.html',
'wm-verified': '2021-06-22T14:28:25.229Z',
author: {
type: 'card',
url: 'https://www.example.com/virginia-woolf.html',
photo: 'https://www.example.com/images/virginia-woolf.jpg',
name: 'Virginia Woolf'
}
}
}
*/
If we change the call to wmverifierto be a different target
to trigger a rejection, we get:
var res = wmverifier('https://www.example.com/some-post', 'https://www.not-mentioned.com');
console.log(res);
/* Output
{
statusCode: 400,
body: 'Source does not mention target',
webmention: false
}
*/
- Assign an ID webmention.io uses "wm-id" as the key, and I would stick with that. However you decide to do that is up to you (hash, increment, etc)
- Store your webmention somewhere A database, a file, anywhere.
- Check if the received webmention already exists, and act accordingly
In theory, there should only be a single combination of
target
andsource
, so if you already have a mention to atarget
from asource
, the newly received mention for that combination could be an update, a deletion, or a duplicate send. Don't store two, find the existing mention and act accordingly. I recommend adding a property on the first receipt of a webmention forwm-received
, the date-time the webmention was first received. Webmention-verifier will updatewm-verified
every time the webmention is verified, which could be frequently depending on how senders send webmentions. - Return the statusCode and body to the sender
- blocklist support
- pingback support