Update authkit documentation & bump to version 0.2.0 (#1124)

Once this PR is closed, I will release appkit.

docs/docs/setup/auth/user/tobira-session.md

@@ -77,6 +77,32 @@ Deno.serve({ port: 7007 }, async (request) => {
 });
 ```
 
+You can also use [the `@opencast/tobira-authkit` package](https://www.npmjs.com/package/@opencast/tobira-authkit) for writing your service.
+That library uses Node.js, gives you type safety (via TypeScript) and performs additional checks.
+
+```ts title="Same login callback written with authkit using Node.js"
+import { LoginCheck, runLoginCallbackServer } from "@opencast/tobira-authkit";
+
+await runLoginCallbackServer({
+  listen: { host: "127.0.0.1", port: 7007 },
+  check,
+});
+
+const check: LoginCheck = async ({ userid, password }) => {
+  if (userid === "peter" && password === "verysecure") {
+    return {
+      outcome: "user",
+      username: "peter",
+      displayName: "Peter Lustig",
+      userRole: "ROLE_USER_PETER",
+      roles: ["ROLE_USER", "ROLE_ANONYMOUS", ...],
+    };
+  } else {
+    return "forbidden";
+  }
+};
+```
+
 
 ## Create sessions manually via `POST /~session`
 

util/authkit/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## v0.2.0
 
 - Add `userRole` to `LoginOutcome`: this reflects the Tobira change of requiring an explicit unique user role.
 - Rename `runServer` to `runLoginProxyServer`

util/authkit/README.md

@@ -1,25 +1,24 @@
 # `@opencast/tobira-authkit`: Helper for building your own Tobira auth handler
 
 This library enables you to build your own login handler that can be used with Tobira.
-Useful mostly for `auth.mode = "login-proxy"`.
-See [the documentation](https://elan-ev.github.io/tobira/setup/auth/login-proxy) for context and more information.
+Useful mostly for using the login callbacks or for intercepting login requests.
+See [the documentation](https://elan-ev.github.io/tobira/next/setup/auth/user/tobira-session) for context and more information.
 
 ## API
 
 The API is described only very briefly here as all public functions and types are documented in code.
-The main entry point (and only non-type export) is `startServer`.
+There are two main entry points: `runLoginCallbackServer` (for `login-callback`) and `runLoginProxyServer` (for intercepting login requests).
 
 ```typescript
-import { startServer, LoginCheck } from "@opencast/tobira-authkit";
+import { runLoginCallbackServer, LoginCheck } from "@opencast/tobira-authkit";
 
-startServer({
+await runLoginCallbackServer({
     check: myCheckFunction,
     // ... other options
 });
 
 const myCheckFunction: LoginCheck = async ({ userid, password }) => { ... };
 ```
 
-This starts an HTTP server that handles login requests by eventually calling the provided `check` function.
+This starts an HTTP server that handles login requests by calling the provided `check` function.
 Said function can either return `"forbidden"` or an object describing the user.
-In the latter case, this library will automatically send a `POST /~session` to Tobira.

util/authkit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencast/tobira-authkit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Helper library to implement your own auth logic for Tobira",
   "author": "The Opencast project",
   "repository": {