Fixed middleware authentication issues

docs/api/authentication.md

@@ -434,6 +434,8 @@ current_user: User = Depends(get_current_admin_api)
 - `InvalidTokenException` - No token or invalid token
 - `InsufficientPermissionsException` - User is not vendor or is admin
 
+**Note:** The `InsufficientPermissionsException` raised here is from `app.exceptions.auth`, which provides general authentication permission checking. This is distinct from `InsufficientTeamPermissionsException` used for team-specific permissions.
+
 **Usage:**
 ```python
 current_user: User = Depends(get_current_vendor_from_cookie_or_header)
@@ -462,6 +464,8 @@ current_user: User = Depends(get_current_vendor_api)
 - `InvalidTokenException` - No token or invalid token
 - `InsufficientPermissionsException` - User is not customer (admin/vendor blocked)
 
+**Note:** The `InsufficientPermissionsException` raised here is from `app.exceptions.auth`, which provides general authentication permission checking. This is distinct from `InsufficientTeamPermissionsException` used for team-specific permissions.
+
 **Usage:**
 ```python
 current_customer: Customer = Depends(get_current_customer_from_cookie_or_header)
@@ -563,6 +567,40 @@ Tokens are validated on every request:
 5. Verify user is active
 6. Check role matches route requirements
 
+#### Token Validation Edge Cases
+
+The token verification process includes comprehensive validation of token claims:
+
+**Required Claims Validation:**
+- **Missing `sub` (User ID)**: Raises `InvalidTokenException("Token missing user identifier")`
+- **Missing `exp` (Expiration)**: Raises `InvalidTokenException("Token missing expiration")`
+- **Expired Token**: Raises `TokenExpiredException()`
+
+**Signature Verification:**
+- **Invalid Signature**: Raises `InvalidTokenException("Could not validate credentials")`
+- **Wrong Algorithm**: Raises `InvalidTokenException()`
+- **Malformed Token**: Raises `InvalidTokenException()`
+
+**Exception Handling Pattern:**
+Custom exceptions (such as those raised for missing claims) are preserved with their specific error messages, allowing for detailed error reporting to clients. This follows the exception handling pattern documented in the [Exception Handling Guide](../development/exception-handling.md).
+
+**Example Error Responses:**
+```json
+{
+  "error_code": "INVALID_TOKEN",
+  "message": "Token missing user identifier",
+  "status_code": 401
+}
+```
+
+```json
+{
+  "error_code": "TOKEN_EXPIRED",
+  "message": "Token has expired",
+  "status_code": 401
+}
+```
+
 ### HTTPS Requirement
 
 **Production Environment:**