Skip to content

Latest commit

 

History

History
199 lines (126 loc) · 8.01 KB

grav-plugin-webmention.md

File metadata and controls

199 lines (126 loc) · 8.01 KB
Raw

Webmention Plugin for Grav CMS

Implementation Home Page URL: https://github.com/Perlkonig/grav-plugin-webmention

Source Code repo URL(s) (optional):

  • 100% open source implementation

Programming Language(s):

Developer(s): Aaron Dalton

Implementation Classes (Sender and/or Receiver): Sender, receiver, and vouch extension

Sending

Discovery Tests (3.1.1)

MUST

Implementation Notes

I've incorporated the following libraries into this plugin:

  • IndieWeb/MentionClient for discovering endpoints and sending notifications.

  • php-mf2 used by IndieWeb/MentionClient to resolve relative URLs and by my code to extract MF2 data from mentioners and vouchers.

Sending Tests (3.1.2)

MUST

  • Accepts HTTP 200 response as a success
  • Accepts HTTP 201 response as a success
  • Accepts HTTP 202 response as a success

Update Tests (3.1.3)

SHOULD

Delete Tests (3.1.4)

SHOULD

Security Considerations (4)

  • The sender avoids sending a Webmention to a loopback address (SHOULD)

Implementation Details

IPv4 only. Checks against reserved IPs as well.

Extensions

This implementation has also implemented the following extensions.

Receiving

Indicate which type of response the receiver provides:

  • HTTP 200 - Receiver synchronously processes the Webmention request (not recommended)
  • HTTP 201 - Receiver creates a status URL the sender can use to check the status of the Webmention
  • HTTP 202 - Receiver processes the Webmention asynchronously

Describe the response body (if any) which is returned in the request:

HTML response, human readable.

Request Verification (3.2.1)

  • Verifies source and target are valid URLs, rejecting with HTTP 400 (MUST)
  • Verifies that target is a valid resource for which the receiver accepts Webmentions, rejecting with HTTP 400 (SHOULD)
  • Ignores fragment when checking if target is supported (SHOULD)

Webmention Verification (3.2.2)

  • Verification is processed asynchronously (SHOULD)
  • Follows at least one HTTP redirect on source URL (MUST)
  • Respects a self-imposed limit on number of HTTP redirects to follow (MUST)

Source URL content-types supported

Please list the content types that your implementation supports when checking if the source document links to the target URL.

  • HTML
  • Other: Treats anything other than 'text/html' as plain text

HTML Verification (3.2.2)

The tests below apply when the source document is HTML.

  • Accepts a Webmention where the target URL is in an <a> tag
  • Accepts a Webmention where the target URL is in an <img> tag
  • Accepts a Webmention where the target URL is in an <video> tag
  • Accepts a Webmention where the target URL is in an <audio> tag
  • Rejects a Webmention where the target URL is in the document as text
  • Rejects a Webmention where the target URL is in an <a> tag inside an HTML comment
  • Rejects a Webmention where the target URL is not in the document

Implementation Details

If content is HTML, it strips all comments and looks for 'href' and 'src' references. Any other content type is naively checked to contain the target string.

Webmention Display/Use

  • The receiver displays data from the source URL on the target post (MAY)

  • The receiver recognizes that the source URL is a "comment" or "reply" to the post

  • using HTML markup: __________

  • The receiver recognizes that the source URL is a "like" of the post

  • using HTML markup: __________

  • The receiver recognizes that the source URL is a "repost" of the post

  • using HTML markup: __________

  • The receiver recognizes that the source URL is an "RSVP" to the post

  • using HTML markup: __________

  • The receiver recognizes additional response types, using markup:

  • Response: __________ using HTML markup: __________

  • (Please add lines like above for additional response types the receiver has implemented)

Please describe any other ways the Webmention is displayed or used if applicable.

How the data is displayed is completely up to the user. The plugin processes the mentions and extracts any embedded MF2 data. If no MF2 data is present, then all the user will have is the URL. The plugin exposes this data to the Grav system and the user can incorporate that data into their themes in any way they wish.

Update Tests (3.2.4)

  • [/] Does not display an update Webmention as a new response (SHOULD)
  • Removes the response when an update Webmention is sent and the source URL returns 200 and no link is found (SHOULD)
  • Updates and stores the information from the primary object at the source URL (MUST)
  • Updates and stores the information from children or descendant objects at the source URL (MAY)

Implementation Details

The first bullet gets a half mark at least. Maybe it's a full mark. The plugin is idempotent, but it never overwrites the initial 'date_received' field. So while any MF2 data would be updated, the user would have no indication that the data had changed. Display is ultimately up to the user, though.

Delete Tests (3.2.4)

  • Recognizes an HTTP 410 response as a delete, and removes the response (SHOULD)

Implementation Details

Any error response will result in the data being marked as invisible. But it's not deleted. The plugin deletes 410 GONE responses from the data when the user approves. The user can of course manually delete any data they choose.

Security Considerations (4)

  • Webmentions are moderated before being displayed (MAY)
  • Webmentions are periodically re-verified (MAY)
  • [/] The receiver ensures any displayed data it properly encoded/filtered to prevent XSS attacks (MUST)
  • Respects a self-imposed limit on the time spent fetching the source URL (SHOULD)
  • Respects a self-imposed limit on the number of bytes fetched from the source URL (SHOULD)
  • The receiver accepts additional parameters or headers, and so has CSRF protection (SHOULD)

Implementation Details

Regarding the half mark in bullet 3: The code uses libraries and language features to do a certain degree of due diligence, but it does not go out of its way. Ultimately the user who displays the data should apply reasonable filters.

Extensions

This implementation has also implemented the following extensions.