HTTP status codes and documentation

api/kiwi_vpn_api/easyrsa.py

@@ -182,8 +182,15 @@ class EasyRSA:
                 *easyrsa_cmd,
             ],
             env={
+                # base settings
                 "EASYRSA_BATCH": "1",
                 "EASYRSA_PKI": str(self.output_directory),
+
+                # always include CA password
+                "EASYRSA_PASSOUT": f"pass:{self.ca_password}",
+                "EASYRSA_PASSIN": f"pass:{self.ca_password}",
+
+                # include env from parameters
                 **easyrsa_env,
             },
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
@@ -218,10 +225,6 @@ class EasyRSA:
             self.__easyrsa(
                 *easyrsa_cmd,
 
-                # include CA password
-                EASYRSA_PASSOUT=f"pass:{self.ca_password}",
-                EASYRSA_PASSIN=f"pass:{self.ca_password}",
-
                 # include algorithm options
                 **EasyRSA.__mapKeyAlgorithm[algorithm],
                 **easyrsa_env,
@@ -296,7 +299,7 @@ class EasyRSA:
         dn: DistinguishedName | None = None,
     ) -> x509.Certificate | None:
         """
-        Issue a client or server certificate
+        Renew a client or server certificate
         """
 
         if dn is None:
@@ -309,9 +312,36 @@ class EasyRSA:
             dn.common_name,
             "nopass",
 
+            # allow renewal 14 days before cert expiry
+            EASYRSA_CERT_RENEW="14",
+
             **dn.easyrsa_env,
         )
 
+    def revoke(
+        self,
+        dn: DistinguishedName | None = None,
+    ) -> bool:
+        """
+        Revoke a client or server certificate
+        """
+
+        if dn is None:
+            dn = DistinguishedName.build()
+
+        try:
+            self.__easyrsa(
+                "revoke",
+                dn.common_name,
+
+                **dn.easyrsa_env,
+            )
+
+        except subprocess.CalledProcessError:
+            return False
+
+        return True
+
 
 EASYRSA = EasyRSA()
 

api/kiwi_vpn_api/routers/_common.py

@@ -23,10 +23,6 @@ class Responses:
     OK = {
         "content": None,
     }
-    INSTALLED = {
-        "description": "kiwi-vpn already installed",
-        "content": None,
-    }
     NOT_INSTALLED = {
         "description": "kiwi-vpn not installed",
         "content": None,
@@ -80,6 +76,8 @@ async def get_current_user(
 
     Status:
 
+    - (400: `kiwi-vpn` not installed)
+    - 401: No auth token provided/not logged in
     - 403: invalid auth token, or user not found
     """
 
@@ -103,12 +101,14 @@ async def get_user_by_name(
 
     Status:
 
-    - 404: user not found
+    - 403: user not found
     """
 
-    # fail if device doesn't exist
+    # don't use error 404 here - possible user enumeration
+
+    # fail if user doesn't exist
     if (user := User.get(user_name)) is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
 
     return user
 

api/kiwi_vpn_api/routers/admin.py

@@ -16,7 +16,7 @@ router = APIRouter(prefix="/admin", tags=["admin"])
     "/install/config",
     responses={
         status.HTTP_200_OK: Responses.OK,
-        status.HTTP_400_BAD_REQUEST: Responses.INSTALLED,
+        status.HTTP_409_CONFLICT: Responses.ENTRY_EXISTS,
     },
 )
 async def initial_configure(
@@ -25,11 +25,15 @@ async def initial_configure(
 ):
     """
     PUT ./install/config: Configure `kiwi-vpn`.
+
+    Status:
+
+    - 409: `kiwi-vpn` already installed
     """
 
     # fail if already configured
     if current_config is not None:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST)
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT)
 
     # create config file, connect to database
     config.save()
@@ -39,10 +43,11 @@ async def initial_configure(
 @router.put(
     "/install/admin",
     responses={
-        status.HTTP_200_OK: Responses.OK,
+        status.HTTP_201_CREATED: Responses.OK,
         status.HTTP_400_BAD_REQUEST: Responses.NOT_INSTALLED,
         status.HTTP_409_CONFLICT: Responses.ENTRY_EXISTS,
     },
+    status_code=status.HTTP_201_CREATED,
 )
 async def create_initial_admin(
     admin_user: UserCreate,
@@ -50,6 +55,10 @@ async def create_initial_admin(
 ):
     """
     PUT ./install/admin: Create the first administrative user.
+
+    Status:
+
+    - 409: not the first user
     """
 
     # fail if any user exists

api/kiwi_vpn_api/routers/device.py

@@ -19,7 +19,6 @@ router = APIRouter(prefix="/device", tags=["device"])
         status.HTTP_400_BAD_REQUEST: Responses.NOT_INSTALLED,
         status.HTTP_401_UNAUTHORIZED: Responses.NEEDS_USER,
         status.HTTP_403_FORBIDDEN: Responses.NEEDS_PERMISSION,
-        status.HTTP_404_NOT_FOUND: Responses.ENTRY_DOESNT_EXIST,
         status.HTTP_409_CONFLICT: Responses.ENTRY_EXISTS,
     },
     response_model=DeviceRead,
@@ -32,6 +31,11 @@ async def add_device(
 ) -> Device:
     """
     POST ./: Create a new device in the database.
+
+    Status:
+
+    - 403: no user permission to create device
+    - 409: device creation unsuccessful
     """
 
     # check permission
@@ -59,6 +63,7 @@ async def add_device(
         status.HTTP_400_BAD_REQUEST: Responses.NOT_INSTALLED,
         status.HTTP_401_UNAUTHORIZED: Responses.NEEDS_USER,
         status.HTTP_403_FORBIDDEN: Responses.NEEDS_PERMISSION,
+        status.HTTP_404_NOT_FOUND: Responses.ENTRY_DOESNT_EXIST,
     },
     response_model=User,
 )
@@ -68,6 +73,10 @@ async def remove_device(
 ):
     """
     DELETE ./{device_id}: Remove a device from the database.
+
+    Status:
+
+    - 403: no user permission to edit device
     """
 
     # check permission
@@ -96,6 +105,11 @@ async def request_certificate_issuance(
 ) -> Device:
     """
     POST ./{device_id}/issue: Request certificate issuance for a device.
+
+    Status:
+
+    - 403: no user permission to edit device
+    - 409: device certificate cannot be "issued"
     """
 
     # check permission
@@ -139,6 +153,11 @@ async def request_certificate_renewal(
 ) -> Device:
     """
     POST ./{device_id}/renew: Request certificate renewal for a device.
+
+    Status:
+
+    - 403: no user permission to edit device
+    - 409: device certificate cannot be "renewed"
     """
 
     # check permission
@@ -162,3 +181,48 @@ async def request_certificate_renewal(
     # return updated device
     device.update()
     return device
+
+
+@router.post(
+    "/{device_id}/revoke",
+    responses={
+        status.HTTP_200_OK: Responses.OK,
+        status.HTTP_400_BAD_REQUEST: Responses.NOT_INSTALLED,
+        status.HTTP_401_UNAUTHORIZED: Responses.NEEDS_USER,
+        status.HTTP_403_FORBIDDEN: Responses.NEEDS_PERMISSION,
+        status.HTTP_404_NOT_FOUND: Responses.ENTRY_DOESNT_EXIST,
+        status.HTTP_409_CONFLICT: Responses.ENTRY_EXISTS,
+    },
+    response_model=DeviceRead,
+)
+async def revoke_certificate(
+    current_user: User = Depends(get_current_user),
+    device: Device = Depends(get_device_by_id),
+) -> Device:
+    """
+    POST ./{device_id}/revoke: Revoke a device certificate.
+
+    Status:
+
+    - 403: no user permission to edit device
+    - 409: device certificate cannot be "revoked"
+    """
+
+    # check permission
+    if not current_user.can_edit(device):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
+
+    # can only revoke a currently certified device
+    if device.approved is not True:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT)
+
+    # revoke the device certificate
+    EASYRSA.revoke(dn=DistinguishedName.build(device))
+
+    # reset the device
+    device.approved = None
+    device.expiry = None
+
+    # return updated device
+    device.update()
+    return device

api/kiwi_vpn_api/routers/user.py

@@ -23,13 +23,25 @@ class Token(BaseModel):
     token_type: str
 
 
-@router.post("/authenticate", response_model=Token)
+@router.post(
+    "/authenticate",
+    responses={
+        status.HTTP_200_OK: Responses.OK,
+        status.HTTP_400_BAD_REQUEST: Responses.NOT_INSTALLED,
+        status.HTTP_401_UNAUTHORIZED: Responses.NEEDS_USER,
+    },
+    response_model=Token,
+)
 async def login(
     form_data: OAuth2PasswordRequestForm = Depends(),
     current_config: Config = Depends(get_current_config),
 ):
     """
     POST ./authenticate: Authenticate a user. Issues a bearer token.
+
+    Status:
+
+    - 401: username/password is incorrect
     """
 
     # try logging in
@@ -49,7 +61,16 @@ async def login(
     return {"access_token": access_token, "token_type": "bearer"}
 
 
-@router.get("/current", response_model=UserRead)
+@router.get(
+    "/current",
+    responses={
+        status.HTTP_200_OK: Responses.OK,
+        status.HTTP_400_BAD_REQUEST: Responses.NOT_INSTALLED,
+        status.HTTP_401_UNAUTHORIZED: Responses.NEEDS_USER,
+        status.HTTP_403_FORBIDDEN: Responses.NEEDS_USER,
+    },
+    response_model=UserRead,
+)
 async def get_current_user_route(
     current_user: User = Depends(get_current_user),
 ):
@@ -78,6 +99,11 @@ async def add_user(
 ) -> User:
     """
     POST ./: Create a new user in the database.
+
+    Status:
+
+    - 403: no user permission to create user
+    - 409: user could not be created
     """
 
     # check permissions
@@ -105,7 +131,6 @@ async def add_user(
         status.HTTP_400_BAD_REQUEST: Responses.NOT_INSTALLED,
         status.HTTP_401_UNAUTHORIZED: Responses.NEEDS_USER,
         status.HTTP_403_FORBIDDEN: Responses.NEEDS_PERMISSION,
-        status.HTTP_404_NOT_FOUND: Responses.ENTRY_DOESNT_EXIST,
     },
     response_model=User,
 )
@@ -115,6 +140,10 @@ async def remove_user(
 ):
     """
     DELETE ./{user_name}: Remove a user from the database.
+
+    Status:
+
+    - 403: no user permission to admin user
     """
 
     # check permissions
@@ -142,6 +171,10 @@ async def extend_tags(
 ):
     """
     POST ./{user_name}/tags: Add tags to a user.
+
+    Status:
+
+    - 403: no user permission to admin user
     """
 
     # check permissions
@@ -169,6 +202,10 @@ async def remove_tags(
 ):
     """
     DELETE ./{user_name}/tags: Remove tags from a user.
+
+    Status:
+
+    - 403: no user permission to admin user
     """
 
     # check permissions