bump package version to 1.5.0

[squeep-authentication-module] / README.md

diff --git a/README.md b/README.md
index 3004f71e272272300f5530f78cdf3a4067ddb0f1..c4234f651480faa38a3891313b64593e588d0973 100644 (file)
--- a/README.md
+++ b/README.md
@@ -14,6 +14,59 @@ Class which fetches and validates identifiers and their credentials from databas
 
 There are some methods for dealing with Basic auth in here as well, but they are not used by sessions.
 
+- `sessionRequiredLocal` redirect to login if session does not represent a valid local user
+- `sessionRequired` redirect to login if session does not represent a valid local user or IA profile
+- `sessionOptionalLocal` check if session represents a valid local user
+- `sessionOptional` check if session represents a valid local user or IA profile
+
+If session is valid for any of these, ctx.session will be populated appropriately.
+
+- `ctx.authenticatedId` will be set to either the valid local identifier or the valid profile
+- `ctx.session.authenticatedIdentifier` will be set if valid local identifier
+- `ctx.session.authenticatedProfile` will be set if valid IA profile
+
 ### SessionManager
 
 Class providing service handler functions for rendering and processing session login and logout pages.
+
+- `getAdminLogin` renders the HTML login form
+- `postAdminLogin` ingests login form data, either validating or denying
+  for local users, or redirecting to IndieAuth server and persisting transient state
+  in session cookie.
+- `getAdminIA` interprets the returning redirect from the IndieAuth server.
+- `getAdminSettings` renders the HTML account settings form
+- `postAdminSettings` ingests and acts on account updates
+
+### Helpers
+
+- `sessionNavLinks` call from app templates to populate navLinks for account settings and logout
+
+### ResourceAuthenticator
+
+Class which fetches and validates resource identifiers and their secrets from database.
+
+Resources are assumed to be other services making API calls.
+
+This is just a time-gated pre-shared-secret HMAC Bearer token scheme.
+
+Default token format is a ':'-separated concatenation of:
+
+- resource identifier, which is a UUID, encoded as 24 bytes in base64url
+- current epoch, encoded as base10 string
+- salt value, randomness encoded as 28 bytes in base64url
+- sha256 HMAC digest of previous data, encoded in base64url
+
+### Other Notes
+
+For the moment, this imposes a web structure of /admin/* for authentication management paths.
+
+The logger used should be able to mask these context fields:
+
+- `ctx.parsedBody.credential`
+- `ctx.parsedBody.credential-old`
+- `ctx.parsedBody.credential-new`
+- `ctx.parsedBody.credential-new-2`
+- `ctx.otpKey`
+- `ctx.otpConfirmBox`
+- `ctx.otpConfirmKey`
+- `ctx.otpState`