feat: add digest auth support to custom authenticator

packages/authenticator-custom/README.md

@@ -26,13 +26,26 @@ app.use(
   nepheleServer({
     adapter: new ExampleAdapter(),
     authenticator: new CustomAuthenticator({
-      auth: async (username, password) => {
-        if (username === 'admin' && password === 'password') {
+      getUser: async (username) => {
+        if (username === 'admin') {
           const user = new User({ username });
           user.someArbitraryPropYouMayNeed = 'somevalue';
           return user;
         }
-
+        return null;
+      },
+      // For Basic authentication.
+      authBasic: async (user, password) => {
+        if (user.username === 'admin' && password === 'password') {
+          return true;
+        }
+        return false;
+      },
+      // For Digest authentication.
+      authDigest: async (user) => {
+        if (user.username === 'admin') {
+          return { password: 'password' };
+        }
         return null;
       },
       realm: 'My WebDAV Server',
@@ -47,13 +60,33 @@ app.listen(port, () => {
 
 # Options / Defaults
 
-- `auth`: A function that takes a username and password and returns a promise that resolves to a user if the authentication succeeds, or null otherwise.
+- `getUser`: A function that takes a username and returns a promise that resolves to a user if the user exists or it's not possible to tell whether they exist, or null otherwise.
 - `realm` = `'Nephele WebDAV Service'`: The realm is the name reported by the server when the user is prompted to authenticate.
+- `key` = `random_uuid()`: A private key used to calculate nonce values for Digest authentication.
+- `nonceTimeout` = `1000 * 60 * 60 * 6`: The number of milliseconds for which a nonce is valid once issued. Defaults to 6 hours.
+- `authBasic`: Authorize a User returned by `getUser` with a password.
+- `authDigest`: Retrieve a User's password or hash for Digest authentication.
 
 ## realm
 
 It should be HTTP header safe (shouldn't include double quotes or semicolon).
 
+## key
+
+If you do not provide one, one will be generated, but this does mean that with Digest authentication, clients will only be able to authenticate to _that_ particular server. If you have multiple servers or multiple instances of Nephele that serve the same source data, you should provide the same key to all of them in order to use Digest authentication correctly.
+
+## authBasic
+
+The returned promise should resolve to true if the user is successfully authenticated, false otherwise.
+
+The Basic mechanism requires the user to submit their username and password in plain text with the request, so only use this if the connection is secured through some means like TLS. If you provide `authBasic`, the server will advertise support for the Basic mechanism.
+
+## authDigest
+
+The returned promise should resolve to the password or hash if the user exists, or null otherwise. If the password is returned, it will be hashed, however, you can also return a prehashed string of SHA256(username:realm:password) or MD5(username:realm:password), depending on the requested algorithm.
+
+The Digest mechansism requires the user to cryptographically hash their password with the request, so it will not divulge their password to eaves droppers. However, it is still less safe than using TLS and Basic authentication. If you provide `authDigest`, the server will advertise support for the Digest mechanism.
+
 # License
 
 Copyright 2022 SciActive Inc

packages/authenticator-custom/package.json

@@ -34,17 +34,18 @@
   "homepage": "https://github.com/sciactive/nephele#readme",
   "devDependencies": {
     "@tsconfig/recommended": "^1.0.1",
-    "@types/basic-auth": "^1.1.3",
     "@types/express": "^4.17.13",
     "@types/jest": "^27.5.0",
+    "@types/uuid": "^8.3.4",
     "express": "^4.18.1",
     "jest": "^28.1.0",
     "ts-jest": "^28.0.2",
     "typescript": "^4.6.4"
   },
   "dependencies": {
-    "basic-auth": "^2.0.1",
-    "nephele": "^1.0.0-alpha.9"
+    "http-auth-utils-hperrin": "^3.0.4",
+    "nephele": "^1.0.0-alpha.9",
+    "uuid": "^8.3.2"
   },
   "engines": {
     "node": ">=16"