From 2b958e08857ad830cdbd1551f490db2ad049cf2e Mon Sep 17 00:00:00 2001 From: Bryan Ashby Date: Sun, 1 Jan 2023 20:43:15 -0700 Subject: [PATCH] Rough docs start --- .../servers/contentservers/web-handlers.md | 9 ++ .../servers/contentservers/web-server.md | 7 +- .../contentservers/webfinger-handler.md | 103 ++++++++++++++++++ 3 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 docs/_docs/servers/contentservers/web-handlers.md create mode 100644 docs/_docs/servers/contentservers/webfinger-handler.md diff --git a/docs/_docs/servers/contentservers/web-handlers.md b/docs/_docs/servers/contentservers/web-handlers.md new file mode 100644 index 00000000..8064c5ae --- /dev/null +++ b/docs/_docs/servers/contentservers/web-handlers.md @@ -0,0 +1,9 @@ +--- +layout: page +title: Web Handlers +--- +Web handlers provide a way to easily add additional _routes_ to your [Web Server](./web-server.md). + +# Built in Web Handler Modules +* [WebFinger](./webfinger-handler.md): Provides basic [WebFinger](https://webfinger.net/) ([RFC7033](https://www.rfc-editor.org/rfc/rfc7033)) support. + diff --git a/docs/_docs/servers/contentservers/web-server.md b/docs/_docs/servers/contentservers/web-server.md index 1a65817e..14c081a4 100644 --- a/docs/_docs/servers/contentservers/web-server.md +++ b/docs/_docs/servers/contentservers/web-server.md @@ -57,8 +57,11 @@ If you don't have a TLS certificate for your domain, a good source for a certifi > :information_source: Keep in mind that the SSL certificate provided by Let's Encrypt's Certbot is by default stored in a privileged location; if your ENIGMA instance is not running as root (which it should not be!), you'll need to copy the SSL certificate somewhere else in order for ENIGMA to use it. -## Static Routes -Static files live relative to the `contentServers.web.staticRoot` path which defaults to `enigma-bbs/www`. This is also commonly known as your "public root". +## Static Root +Static files live relative to the `contentServers.web.staticRoot` path which defaults to `enigma-bbs/www`. This is also commonly known as your "public root" directory. ## Custom Error Pages Customized error pages can be created for [HTTP error codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error) by providing a `.html` file in the *static routes* area. For example: `404.html`. + +## Web Handlers +[Web Handlers](./web-handlers.md) are loaded by the web content server and provide a easy way for adding additional routes & functionality to ENiGMA. \ No newline at end of file diff --git a/docs/_docs/servers/contentservers/webfinger-handler.md b/docs/_docs/servers/contentservers/webfinger-handler.md new file mode 100644 index 00000000..c375f1cc --- /dev/null +++ b/docs/_docs/servers/contentservers/webfinger-handler.md @@ -0,0 +1,103 @@ +--- +layout: page +title: WebFinger Handler +--- +The WebFinger ([webfinger.js](/core/servers/content/web_handlers/webfinger.js)) [Handler](./web-handlers.md) provides basic [WebFinger](https://webfinger.net/) ([RFC7033](https://www.rfc-editor.org/rfc/rfc7033)) support, enabling servers such as those participating in the [Mastodon](https://en.wikipedia.org/wiki/Mastodon_(social_network)) [Fediverse](https://en.wikipedia.org/wiki/Fediverse) to discover basic information about a user. + +# Supported Features +* [profile-page](https://webfinger.net/rel/profile-page/) +* [ActivityStream URI](https://www.w3.org/TR/activitystreams-core/) via rel of `self` and of type `application/activity+json` +* Subscription URI template via rel of `http://ostatus.org/schema/1.0/subscribe` + +# Configuration +By default, the WebFinger handler is not enabled. To enable, at a minimum set `contentServers.web.handlers.webFinger.enabled` to `true` in `config.hjson`: + +```js +contentServers: { + web: { + handlers: { + webFinger: { + enabled: true // wow, much nest! + } + } + } +} +``` + +## Configuration Keys +| Key | Description | +| ----|-------------| +| `enabled` | Boolean. Set to `true` to enable WebFinger services | +| `profileTemplate` | String. Provide a fully qualified, or relative to [static root](./web-server.md#static-root) path to a template file for fetching profile information. See [Profile Template](#profile-template) for more information. + +## Profile Template +A profile template file can offer flexibility as to what information, the format, and MIME type served by the [profile-page](https://webfinger.net/rel/profile-page/) WebFinger query. Set the `profileTemplate` key in your `webFinger` configuration block to a path to serve as the template. The MIME type will be determined by the file's extension: + +```js +contentServers: { + web: { + handlers: { + webFinger: { + enabled: true + profileTemplate: './wf/fancy-profile.html' + } + } + } +} +``` + +> :information_source: A sample template can be found at `www/wf/profile.template.html` + +# Example Session +```shell +# WebFinger query +> http get 'https://xibalba.l33t.codes/.well-known/webfinger?resource=acct:NuSkooler@xibalba.l33t.codes' +HTTP/1.1 200 OK +Connection: keep-alive +Content-Length: 558 +Content-Type: application/jrd+json +Date: Mon, 02 Jan 2023 03:36:20 GMT +Keep-Alive: timeout=5 + +{ + "aliases": [ + "https://xibalba.l33t.codes/_enig/wf/@NuSkooler", + "https://xibalba.l33t.codes/_enig/ap/users/NuSkooler" + ], + "links": [ + { + "href": "https://xibalba.l33t.codes/_enig/wf/@NuSkooler", + "rel": "https://webfinger.net/rel/profile-page", + "type": "text/plain" + }, + { + "href": "https://xibalba.l33t.codes/_enig/ap/users/NuSkooler", + "rel": "self", + "type": "application/activity+json" + }, + { + "rel": "http://ostatus.org/schema/1.0/subscribe", + "template": "http://xibalba.l33t.codes/_enig/ap/authorize_interaction?uri={uri}" + } + ], + "subject": "acct:NuSkooler@xibalba.l33t.codes" +} +``` + +```shell +# Now we can fetch the profile +> http get 'https://xibalba.l33t.codes/_enig/wf/@NuSkooler' +HTTP/1.1 200 OK +Connection: keep-alive +Content-Length: 116 +Content-Type: text/plain +Date: Mon, 02 Jan 2023 03:41:19 GMT +Keep-Alive: timeout=5 + +User information for: NuSkooler + +Real Name: Bryan Ashby +Login Count: 432 +Affiliations: ENiG +Achievement Points: 405 +``` \ No newline at end of file