feature: users sign in to the web service, and only members of admins manage the router.

debian-package/src/usr/lib/vpn-router/web

@@ -15,10 +15,16 @@ Pages:
            profile, and TOTP enrolment (see users())
   /groups  the groups of the router's directory: list, add, rename or describe, remove, and
            add and take out members (see groups())
+  /auth    sign-in with a user's password and TOTP code, refresh and sign-out (see auth())
 
-/config, /users and /groups need an HS256 JWT in an Authorization: Bearer header that is signed
-with web.jwt_secret and expires within ten minutes; they are not served (404) while
-web.jwt_secret is not set.
+/config, /users and /groups need an HS256 JWT in an Authorization: Bearer header signed with
+vpnrouter_auth.WEB_KEY (see vpnrouter_auth.verify). A token of /auth names a user in sub, who
+must be a member of vpnrouter_users.ADMIN_GROUP; a token of vpn-router-token has the admin
+claim, and only such a token may change ADMIN_GROUP: create, rename to it, change, remove it,
+add or take out its members, and remove one of its members. These paths and /auth are not
+served (404) while the key does not exist. /auth is limited to AUTH_LIMIT calls per client
+address in AUTH_WINDOW seconds; the address of a call from one of web.trusted_proxies, by
+default the address the service listens on, is the last entry of its X-Forwarded-For header.
 
 / and /status show only the status: whether the services run, the package version, whether
 Docker is installed, and the state of site-to-site, road-warrior (IPsec P2S), OpenVPN and
@@ -28,15 +34,13 @@ The service needs nothing else to start and does not end on its own. A discovery
 out the internal address from /etc/vpn-router/vpn-router.json as general.mode directs, with
 web.port and web.enabled, every DISCOVERY_SECONDS, and runs the server thread there: it starts
 it, moves it when the address or the port changes, and stops it while the service is disabled
-or the address is not known. Every request reads what it needs when it is made: the token secret
-from the configuration, and the features of the router and the facts shown by /config from
+or the address is not known. Every request reads what it needs when it is made: the signing
+key, the configuration, and the features of the router and the facts shown by /config from
 /run/vpn-router/web.json, which vpn-router-setup writes. Before setup has written that file
 the router has no features, and /config shows no configuration or interfaces.
 """
 
-import base64
-import hashlib
-import hmac
+import collections
 import json
 import os
 import signal
@@ -50,7 +54,10 @@ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 sys.path.insert(0, os.path.dirname(os.path.realpath(__file__)))
 
 import ldap
+import psycopg
 
+import vpnrouter
+import vpnrouter_auth
 import vpnrouter_net
 import vpnrouter_users
 
@@ -65,11 +72,9 @@ DISCOVERY_SECONDS = 30
 COMMAND_TIMEOUT = 5
 CACHE_SECONDS = 2
 
-#: Seconds of clock difference accepted between a token and this router.
-LEEWAY = 60
-
-#: The longest a token may be valid, from now, in seconds.
-MAX_LIFETIME = 600
+#: The calls of /auth allowed per client address in AUTH_WINDOW seconds.
+AUTH_LIMIT = 10
+AUTH_WINDOW = 60
 
 TAILWIND = 'https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4'
 
@@ -82,11 +87,15 @@ OPENVPN_STATUS = '/run/openvpn-server/status-vpn-router.log'
 BODY_LIMIT = 4096
 
 #: The HTTP status for each status of a vpnrouter_users.Failure; any other is 500.
-USER_STATUS = {2: 400, 3: 404, 4: 409}
+USER_STATUS = {2: 400, 3: 404, 4: 409, 5: 401}
 
 _cache = {'at': 0.0, 'data': None}
 _lock = threading.Lock()
 
+#: The times of the recent /auth calls of each client address.
+_auth_calls = collections.defaultdict(collections.deque)
+_auth_lock = threading.Lock()
+
 
 def read_json(path):
     """The object in a JSON file, or {} when the file is missing or holds no object."""
@@ -105,14 +114,12 @@ def section(configuration, name):
 
 
 def current():
-    """What a request needs, read now: the features and facts setup resolved, and the token secret.
+    """What a request needs, read now: the features and facts setup resolved, and the signing key.
 
-    Before setup has run the router has no features, and without a secret /config and /users are
-    not served.
+    Before setup has run the router has no features, and without a key the protected paths and
+    /auth are not served.
     """
-    state = read_json(STATE_FILE)
-    secret = section(read_json(CONFIG_FILE), 'web').get('jwt_secret')
-    return dict(state, jwt_secret=secret if isinstance(secret, str) else '')
+    return dict(read_json(STATE_FILE), key=vpnrouter_auth.key())
 
 
 def run(*args):
@@ -253,37 +260,6 @@ def collect(state):
     return status
 
 
-def b64decode(part):
-    return base64.urlsafe_b64decode(part + '=' * (-len(part) % 4))
-
-
-def verify(token, secret):
-    """The claims of a token signed with HS256 by the secret, or None when it is not acceptable.
-
-    Only HS256 is accepted, so a token cannot choose a weaker algorithm. The token
-    must expire (exp), and not later than MAX_LIFETIME seconds from now, so that a
-    stolen token is of little use; LEEWAY seconds of clock difference are allowed.
-    """
-    try:
-        header, payload, signature = token.split('.')
-        if json.loads(b64decode(header)).get('alg') != 'HS256':
-            return None
-        expected = hmac.new(secret.encode(), f'{header}.{payload}'.encode(), hashlib.sha256).digest()
-        if not hmac.compare_digest(expected, b64decode(signature)):
-            return None
-        claims = json.loads(b64decode(payload))
-        now = time.time()
-        expires = claims['exp']
-        if isinstance(expires, bool) or not isinstance(expires, (int, float)) or not now - LEEWAY <= expires <= now + MAX_LIFETIME + LEEWAY:
-            return None
-        not_before = claims.get('nbf')
-        if not_before is not None and (isinstance(not_before, bool) or not isinstance(not_before, (int, float)) or not_before > now + LEEWAY):
-            return None
-    except (ValueError, KeyError, TypeError, AttributeError):
-        return None
-    return claims
-
-
 def lines_of(*args):
     """The output lines of a command, or None when it fails."""
     result = run(*args)
@@ -420,6 +396,7 @@ def users(state, method, path, body):
       PUT    /users/<name>/password   set the password: {"password": ...}
       POST   /users/<name>/disable    lock the user out of OpenVPN
       POST   /users/<name>/enable     let the user in again
+      POST   /users/<name>/unlock     end a lockout after failed logins
       DELETE /users/<name>            remove the user and revoke the certificate
       GET    /users/<name>/profile    the OpenVPN client profile
       POST   /users/<name>/otp        a new TOTP secret and its otpauth URI; nothing is stored
@@ -439,6 +416,7 @@ def users(state, method, path, body):
         ('PUT', 3, 'password'): lambda connection: vpnrouter_users.passwd(connection, name, body.get('password')),
         ('POST', 3, 'disable'): lambda connection: vpnrouter_users.disable(connection, name),
         ('POST', 3, 'enable'): lambda connection: vpnrouter_users.enable(connection, name),
+        ('POST', 3, 'unlock'): lambda connection: vpnrouter_users.unlock(connection, name),
         ('DELETE', 2, None): lambda connection: vpnrouter_users.remove(connection, name),
         ('GET', 3, 'profile'): lambda connection: vpnrouter_users.profile(connection, name),
         ('POST', 3, 'otp'): lambda connection: vpnrouter_users.otp_new(connection, name),
@@ -454,6 +432,8 @@ def users(state, method, path, body):
         return USER_STATUS.get(failure.status, 500), {'error': str(failure)}
     except (ldap.LDAPError, OSError) as exc:
         return 500, {'error': f'the user directory failed: {exc}'}
+    except psycopg.Error as exc:
+        return 500, {'error': f'the token database failed: {exc}'}
     except SystemExit:
         # vpnrouter ends with SystemExit on a configuration it cannot read; it has printed the reason.
         return 500, {'error': 'the router configuration cannot be read'}
@@ -498,6 +478,85 @@ def groups(state, method, path, body):
     return (201 if route == ('POST', 1, None) else 200), document
 
 
+def changes_admins(connection, method, parts, body):
+    """Whether a /users or /groups request creates, renames to, changes or removes ADMIN_GROUP, or removes a member of it."""
+    admins = vpnrouter_users.ADMIN_GROUP
+    if parts[0] == 'groups':
+        if method == 'POST' and len(parts) == 1:
+            return body.get('name') == admins
+        if method != 'GET' and len(parts) > 1 and parts[1] == admins:
+            return True
+        return method == 'PUT' and len(parts) == 2 and body.get('name') == admins
+    if parts[0] == 'users' and method == 'DELETE' and len(parts) == 2:
+        return admins in vpnrouter_users.groups_of(connection, parts[1])
+    return False
+
+
+def refusal(claims, method, path, body):
+    """Why the holder of the claims may not make the request to a protected path, or '' when it may."""
+    if claims.get('admin') is True:
+        return ''
+    name = claims.get('sub')
+    if not isinstance(name, str):
+        return 'the token names no user'
+    admins = vpnrouter_users.ADMIN_GROUP
+    with vpnrouter_users.session() as connection:
+        if not vpnrouter_users.is_admin(connection, name):
+            return f'user {name} is not a member of {admins}'
+        if changes_admins(connection, method, path.strip('/').split('/'), body if isinstance(body, dict) else {}):
+            return f'only a token of vpn-router-token may change the group {admins} or remove its members'
+    return ''
+
+
+def auth(path, body):
+    """Answer a POST to /auth with vpnrouter_users and vpnrouter_auth: the HTTP status and the JSON document.
+
+      POST /auth           sign in: {"name", "password", "code"?}; the tokens
+      POST /auth/refresh   {"refresh_token"}; new tokens, the refresh token used up
+      POST /auth/logout    {"refresh_token"}; the refresh token revoked
+    """
+    if not isinstance(body, dict):
+        return 400, {'error': 'the body must be a JSON object'}
+    try:
+        cfg = vpnrouter.load_config()
+        if path == '/auth':
+            vpnrouter_users.login(body.get('name'), body.get('password'), body.get('code'))
+            return 200, vpnrouter_auth.issue(cfg, body['name'])
+        name = vpnrouter_auth.take(cfg, body.get('refresh_token'))
+        if path == '/auth/logout':
+            return 200, {'revoked': name is not None}
+        if name is None:
+            return 401, {'error': 'the refresh token is not valid'}
+        with vpnrouter_users.session() as connection:
+            user = vpnrouter_users.summary(vpnrouter_users.entry(connection, name))
+        if not user['enabled'] or user['locked']:
+            return 401, {'error': f'user {name} is disabled or locked'}
+        return 200, vpnrouter_auth.issue(cfg, name)
+    except vpnrouter_users.Failure as failure:
+        return (401 if failure.status == 3 else USER_STATUS.get(failure.status, 500)), {'error': str(failure)}
+    except (ldap.LDAPError, OSError) as exc:
+        return 500, {'error': f'the user directory failed: {exc}'}
+    except psycopg.Error as exc:
+        return 500, {'error': f'the token database failed: {exc}'}
+    except SystemExit:
+        return 500, {'error': 'the router configuration cannot be read'}
+
+
+def auth_wait(address):
+    """Seconds until the client address may call /auth again, 0 when it may now; a call that may is counted."""
+    now = time.monotonic()
+    with _auth_lock:
+        for idle in [key for key, times in _auth_calls.items() if times[-1] <= now - AUTH_WINDOW]:
+            del _auth_calls[idle]
+        calls = _auth_calls[address]
+        while calls and calls[0] <= now - AUTH_WINDOW:
+            calls.popleft()
+        if len(calls) >= AUTH_LIMIT:
+            return int(calls[0] + AUTH_WINDOW - now) + 1
+        calls.append(now)
+        return 0
+
+
 class Handler(BaseHTTPRequestHandler):
     protocol_version = 'HTTP/1.1'
 
@@ -508,29 +567,65 @@ class Handler(BaseHTTPRequestHandler):
                 _cache['at'] = time.monotonic()
             return _cache['data']
 
-    def authorized(self, secret):
-        """Whether the request carries a token signed with the secret; False also while no secret is set."""
+    def claims(self, secret):
+        """The claims of the request's token signed with the secret, or None without an acceptable one."""
         header = self.headers.get('Authorization', '')
-        return bool(secret) and header.startswith('Bearer ') and verify(header[7:].strip(), secret) is not None
+        return vpnrouter_auth.verify(header[7:].strip(), secret) if header.startswith('Bearer ') else None
+
+    def client(self):
+        """The client address: the last X-Forwarded-For entry when the peer is a trusted proxy, else the peer."""
+        peer = self.client_address[0]
+        trusted = section(read_json(CONFIG_FILE), 'web').get('trusted_proxies') or [self.server.server_address[0]]
+        forwarded = self.headers.get('X-Forwarded-For', '')
+        if isinstance(trusted, list) and peer in trusted and forwarded.strip():
+            return forwarded.split(',')[-1].strip()
+        return peer
+
+    def refusal(self, claims, path, payload):
+        """The HTTP status and the message that refuse a request to a protected path, or None when it may be made."""
+        try:
+            reason = refusal(claims, self.command, path, payload)
+        except (ldap.LDAPError, OSError) as exc:
+            return 500, f'the user directory failed: {exc}'
+        return (403, reason) if reason else None
 
     def answer(self, send_body):
         path = self.path.split('?', 1)[0]
         extra = []
+        self.principal = None
         # A body that is not read must not be taken for the next request.
         if self.command not in ('GET', 'HEAD'):
             self.close_connection = True
         directory = next((name for name in ('users', 'groups') if path == f'/{name}' or path.startswith(f'/{name}/')), None)
         protected = path == '/config' or directory is not None
-        state = current() if protected else {}
-        if protected and not state['jwt_secret']:
+        signing = path in ('/auth', '/auth/refresh', '/auth/logout')
+        state = current() if protected or signing else {}
+        claims = self.claims(state['key']) if protected and state['key'] else None
+        payload = self.request_body() if (protected or signing) and self.command not in ('GET', 'HEAD') else None
+        if claims is not None:
+            self.principal = 'admin' if claims.get('admin') is True else claims.get('sub')
+        if (protected or signing) and not state['key']:
             body, kind, code = b'Not found\n', 'text/plain; charset=utf-8', 404
-        elif protected and not self.authorized(state['jwt_secret']):
+        elif signing and self.command != 'POST':
+            body, kind, code = b'Method not allowed\n', 'text/plain; charset=utf-8', 405
+        elif signing:
+            wait = auth_wait(self.client()) if path != '/auth/logout' else 0
+            if wait:
+                code, document = 429, {'error': f'too many sign-in calls; retry in {wait} seconds'}
+                extra.append(('Retry-After', str(wait)))
+            else:
+                code, document = auth(path, payload)
+            body, kind = json.dumps(document, indent=2).encode() + b'\n', 'application/json'
+        elif protected and claims is None:
             body, kind, code = b'Unauthorized\n', 'text/plain; charset=utf-8', 401
             extra.append(('WWW-Authenticate', 'Bearer'))
+        elif protected and (refused := self.refusal(claims, path, payload)):
+            code, kind = refused[0], 'application/json'
+            body = json.dumps({'error': refused[1]}, indent=2).encode() + b'\n'
         elif path == '/config' and self.command in ('GET', 'HEAD'):
             body, kind, code = json.dumps(details(state), indent=2).encode() + b'\n', 'application/json', 200
         elif protected and path != '/config':
-            code, document = (users if directory == 'users' else groups)(state, self.command, path, self.request_body())
+            code, document = (users if directory == 'users' else groups)(state, self.command, path, payload)
             body, kind = json.dumps(document, indent=2).encode() + b'\n', 'application/json'
         elif self.command not in ('GET', 'HEAD'):
             body, kind, code = b'Method not allowed\n', 'text/plain; charset=utf-8', 405
@@ -584,7 +679,8 @@ class Handler(BaseHTTPRequestHandler):
         self.answer(True)
 
     def log_message(self, format, *args):
-        sys.stderr.write('%s - - [%s] %s\n' % (self.client_address[0], self.log_date_time_string(), format % args))
+        principal = getattr(self, 'principal', None) or '-'
+        sys.stderr.write('%s - %s [%s] %s\n' % (self.client_address[0], principal, self.log_date_time_string(), format % args))
 
 
 def wanted():