SVNmentions

This is an endpoint to compliment mod_dav_svn by adding a webmentions receiver that can update an HTML document within SVN.

This is complimented by a webmentions sender hook.

Security

Note that SVNmentions obtains direct access to the SVN repository and bypasses any Apache-level Authorization that has been set up. This, and its ability to inject HTML into the repository makes it an attack vector. Consider extending with or applying some amount of spam or other filtering to reduce the risk.

Setup

Note: requires PHP 8.3+

1. Run make debian-package-dependencies to install dependent build Debian packages
2. Run make debian-package to build package locally
3. Run dpkg -i package/SVNmentions_X.X.X_all.deb to install package locally
   • Apache HTTPd
   • mod_dav_svn
   • PHP
   • svn (TODO: replace commandline with installing bindings php5-svn/PECL svn)
4. Configure! (Replace <> with real values.)

   <Location </svn>>
       DAV svn
       SVNParentPath </path/to/parent>
   </Location>
   AliasMatch ^/SVNmentions$ /usr/src/SVNmentions/SVNmentions.php
   <Directory "usr/src/SVNmentions/">
       SetEnv Context '{"SVNParentPath":"</path/to/parent>","SVNLocationPath":"</svn>"}'
       Require all granted
   </Directory>
   

Usage

Apache Configuration Must Include

• SetEnv Context with a JSON string for proper substitutions (and, yes, these values are duplicated in your config)
  • SVNParentPath - filesystem path to parent directory of repository - this matches the SVNParentPath directive
  • SVNLocationPath - webspace path that is parent to the repository - this matches the Location directive

Apache Configuration Optional

• SetEnv WebmentionUsername <SVNmention> - the username that will be used during the content update to commit to the repository
• SetEnv WebmentionsCommitMessage "<SVNmention received>" - the commit message used during the content update to commit to the repository
• SetEnv WebmentionsAuthz <svn property> - the SVN property that you set will act as an allowlist of services that have permission to Webmention the file it is set on - I recommend the value authz:webmention (to follow the convention in svn-auth)
  • if the property value has anonymous, then all services will have permission
  • the absence of this configuration will act the same as anonymous
• SetEnv WebmentionsClientID </path/to/client> - for SVNmentions' client ID to be https://example.com/path/to/client (See Client ID Metadata for more information)
• SetEnv WebmentionsAgent 'SVNmentions (https://github.com/carrvo/SVNmentions) curl/8.5.0' - customize the user agent for outgoing requests
• SetEnv LocalCommentLimit <int> - the maximum number of characters accepted

Supporting Endpoints Must Include

These endpoints must be within an SVN repository and must reside on the same domain as the webmention endpoint.

<link rel="webmention" href="https://example.com/SVNmentions" />

<div id="webmentions">
    <div id="webmention-comments" />
</div>

Supporting Endpoints Minimal Recommended Style

<style>
#webmention-comments iframe {
	display: block;
	width: 80%;
}
</style>

Supporting Endpoints Optional

You can customize the embedded HTML by providing templates through SVN properties. Note that your template will always have the id attribute populated internally.

SVN Properties Supported

• webmention:inject - determines which direction to inject the template: beginning or prepend, end or append, default is the same as end/append
• webmention:default - default template to use when no other types are supported (this will show under <div id="webmention-comments" />)
• webmention:local-comment - template for local comments (this will show under <div id="webmention-comments" />)

You can use the commands svn propget, svn propset, and svn propedit to inspect and edit. Alternatively you can use client features (such as with TortoiseSVN) to inspect and edit.

Template Variables Supported

• <?source?> - escaped source URI
• <?source:unsafe?> - raw source URI (this may be safe because it was queried so it must be a legitimate URI)
• <?content?> - escaped local comment
• <?content:unsafe?> - raw local comment

The default template is

<a href="<?source:unsafe?>" ><?source?></a><iframe src="<?source:unsafe?>" />'

Non-Standard Webmentions

Alternatively you can receive non-standard Webmentions. This is useful for mime-types that cannot have the destination embedded into their file content (such as image files).

Local Comments

Local comments do not have a source. However, the pattern for non-standard Webmentions can still be be leveraged by including the additional post fields:

• type=local-comment
• content=XXXXXXX

Example HTML for a webpage:

<form action="https://example.com/SVNmentions" method="POST">
    <input type="hidden" name="target" value="http://example.com/webpage.html">
    <input type="hidden" name="type" value="local-comment">
    <label for="comment">Comment</label>
    <br />
    <textarea id="comment" name="content" rows="4" cols="50"></textarea>
    <br />
    <input type="submit" value="Submit">
</form>

WebDAV

These non-standard Webmentions will be sent with the additional post fields:

• type=webdav
• property=XXXXXXX - this property will be verified with a PROPFIND to ensure it references the target (instead of a GET to verify through the content)

For an example sender see the webmentions sender hook description.

Testing

Tested with webmention-testpinger.

License

Copyright 2024 by carrvo

I have not decided on which license to declare as of yet.