Merge pull request #2428 from slingamn/manual

documentation updates

CHANGELOG.md

@@ -7,7 +7,7 @@ We're pleased to be publishing the release candidate for v2.19.0 (the official r
 
 This release includes changes to the config file format, one of which is not backwards-compatible (see below to determine whether you are affected). It includes no changes to the database file format.
 
-Many thanks to [@andymandias](https://github.com/andymandias), [@emersion](https://github.com/emersion), [@englut](https://github.com/englut), [@Jokler](https://github.com/Jokler), [@jwheare](https://github.com/jwheare), [@KlaasT](https://github.com/KlaasT), [@luxaritas](https://github.com/luxaritas), [@SAY-5](https://github.com/SAY-5), [@skizzerz](https://github.com/skizzerz), [@ValwareIRC](https://github.com/ValwareIRC), and [@whitequark](https://github.com/whitequark) for helpful discussions, contributing patches, reporting issues, and helping test.
+Many thanks to [@andymandias](https://github.com/andymandias), dzwdz, [@emersion](https://github.com/emersion), [@englut](https://github.com/englut), [@Jokler](https://github.com/Jokler), [@jwheare](https://github.com/jwheare), [@KlaasT](https://github.com/KlaasT), [@luxaritas](https://github.com/luxaritas), [@SAY-5](https://github.com/SAY-5), [@skizzerz](https://github.com/skizzerz), [@tacerus](https://github.com/tacerus), [@ValwareIRC](https://github.com/ValwareIRC), and [@whitequark](https://github.com/whitequark) for helpful discussions, contributing patches, reporting issues, and helping test.
 
 ### Compatibility breaks
 * The `extjwt` configuration block now takes `algorithm` (`hmac`, `rsa`, or `eddsa`) and either `key` or `key-file` to configure the signing key (see `default.yaml` for examples). If you are using `extjwt`, the suggested upgrade path is to add the new keys before upgrading (duplicating the legacy keys `secret` and/or `rsa-private-key-file`), upgrade Ergo, then once the new version is confirmed stable, delete the legacy keys. (#2385)

docs/MANUAL.md

@@ -66,6 +66,7 @@ _Copyright © Daniel Oaks <daniel@danieloaks.net>, Shivaram Lingamneni <slingamn
     - [API](#api)
     - [External authentication systems](#external-authentication-systems)
     - [DNSBLs and other IP checking systems](#dnsbls-and-other-ip-checking-systems)
+    - [draft/authtoken](#draftauthtoken)
 - [Acknowledgements](#acknowledgements)
 
 --------------------------------------------------------------------------------------------
@@ -1269,6 +1270,17 @@ The output is a JSON dictionary with the following keys:
 * `banMessage`: a message to send to the user indicating why they are banned
 * `error`, containing a human-readable description of the authentication error to be logged if applicable
 
+## draft/authtoken
+
+Ergo 2.19 adds support for [draft/authtoken](https://github.com/ircv3/ircv3-specifications/pull/602), a proposed IRCv3 mechanism for integrating with external services. Although Ergo implements the full specification, including online token verification, Ergo's tokens are signed JWTs and the intent is for Ergo-aware services to verify them locally, without contacting the Ergo server. Here are the hardening recommendations for draft/authtoken in Ergo:
+
+* Use the `hmac` algorithm with a strong, unique key for each service. (You can generate a suitable key with `ergo gentoken`.)
+* The expiration time should be no higher than 5 minutes.
+* When processing a token, validate the signature according to the `HS256` algorithm, then validate the following claims:
+  * `aud` should be the service's endpoint URL
+  * `acc` should be the user's account name (without case normalization)
+  * If present, `scope` is the channel name and `chmode` is the user's operator level in the channel (e.g. `o` for operator or `h` for halfop).
+
 --------------------------------------------------------------------------------------------