Make API auth contexts safe to copy across threads

README.md

@@ -19,6 +19,24 @@ packages repository]. The url is
 [nimble configuration]: https://github.com/nim-lang/nimble#configuration
 [JDB Software Nim packages]: https://git.jdb-software.com/jdb/nim-packages
 
+## Authentication contexts and threads
+
+`ApiAuthContext` is a value object. Assigning it copies its configuration and
+signing-key cache, so each worker can own a context and refresh keys independently.
+Copy it before handing it to a worker, and synchronize any access to a context
+that another thread may be modifying.
+
+Use a `var ApiAuthContext` for `addSigningKeys`, `findSigningKey`, `validateJWT`,
+and `extractValidJwt`: lookup and validation can fetch and cache issuer keys.
+`createSignedJWT`, `newApiAccessToken`, and `createSessionCookies` also accept
+immutable contexts. Existing callers using `let` for a context that validates
+tokens must switch to `var`; use `Option[ApiAuthContext]` instead of `nil` when
+absence needs to be represented.
+
+The cache stores keys directly in a `Table[string, JwkSet]`, using the value
+semantics provided by `jwt_full` 0.5.0 or later. Context copies own independent
+key caches, and key lookup and signing use the parsed keys directly.
+
 ## License
 
 Buffoonery is available under two licenses depending on usage.