Error Handling - FeitianTech/postquantum-webauthn-platform GitHub Wiki
Error Handling
Table of Contents
- Introduction
- Error Response Format
- HTTP Status Codes
- Backend Error Handling
- Frontend Error Handling
- WebAuthn Specific Errors
- Error Presentation in UI
- Debugging and Troubleshooting
- Conclusion
Introduction
The Post-Quantum WebAuthn Platform implements a comprehensive error handling system across both backend and frontend components. This documentation details the error codes, messages, and handling patterns used throughout the application, with a focus on WebAuthn operations, validation errors, authentication failures, and system errors. The platform follows consistent patterns for error transformation, logging, and user-friendly message presentation.
Section sources
Error Response Format
The API returns errors in a standardized JSON format that includes error messages and additional context when available. The basic structure consists of an "error" field containing a descriptive message. In some cases, additional fields may be included to provide more specific information about the error condition.
For validation and processing errors, the response typically contains a simple error message that describes the issue encountered. The frontend transforms these server responses into user-friendly messages, while also handling browser-level WebAuthn errors directly.
flowchart TD
A[Error Occurs] --> B{Error Type}
B --> C[HTTP Error]
B --> D[Validation Error]
B --> E[WebAuthn Browser Error]
C --> F[Return JSON with error message]
D --> F
E --> G[Transform to user-friendly message]
F --> H[Display in UI]
G --> H
**Diagram sources **
Section sources
HTTP Status Codes
The platform uses standard HTTP status codes to indicate the result of API requests. These codes are used in conjunction with descriptive error messages in the response body to provide clear feedback about request outcomes.
400 Bad Request is returned for validation errors or malformed requests, such as when required parameters are missing or incorrectly formatted. 404 Not Found is used when requested resources cannot be located, such as when attempting to authenticate with a username that has no registered credentials. 500 Internal Server Error indicates unexpected server-side issues, while 503 Service Unavailable may be used during maintenance or when dependencies are unavailable.
flowchart LR
A[Client Request] --> B{Request Valid?}
B --> |Yes| C[Process Request]
B --> |No| D[400 Bad Request]
C --> E{Resource Exists?}
E --> |Yes| F[200 OK]
E --> |No| G[404 Not Found]
C --> H{Server Error?}
H --> |Yes| I[500 Internal Server Error]
H --> |No| F
**Diagram sources **
Section sources
Backend Error Handling
The backend implements error handling through Flask's abort function and explicit JSON responses with error messages. In the routes, validation is performed on incoming requests, and appropriate errors are returned when requirements are not met. The system also handles exceptions that occur during processing, converting them to appropriate HTTP responses.
In the attestation module, detailed validation is performed on WebAuthn responses, with specific error codes added to the results dictionary when validation fails. These include checks for client data type validity, challenge matching, origin verification, and RP ID hash validation. The system also validates user presence, user verification requirements, and credential data integrity.
flowchart TD
A[Request Received] --> B[Validate Parameters]
B --> C{Valid?}
C --> |No| D[Return 400 with error]
C --> |Yes| E[Process Request]
E --> F{Error Occurred?}
F --> |Yes| G[Log Error]
F --> |Yes| H[Return appropriate HTTP error]
F --> |No| I[Return Success]
G --> H
**Diagram sources **
Section sources
Frontend Error Handling
The frontend JavaScript code implements comprehensive error handling for WebAuthn operations, transforming low-level browser errors into user-friendly messages. The system catches exceptions from the WebAuthn API and maps them to descriptive messages that help users understand what went wrong and how to proceed.
Three primary WebAuthn error types are handled: NotAllowedError, InvalidStateError, and SecurityError. NotAllowedError typically indicates that the user cancelled the operation or no compatible authenticator is available. InvalidStateError suggests issues with the authenticator state or credential configuration. SecurityError usually relates to connection issues or security policy violations.
flowchart TD
A[WebAuthn Operation] --> B{Success?}
B --> |No| C[Capture Error]
C --> D{Error Type}
D --> E[NotAllowedError]
D --> F[InvalidStateError]
D --> G[SecurityError]
D --> H[Other Error]
E --> I[User cancelled or authenticator not available]
F --> J[Authenticator error or invalid credential]
G --> K[Security error - check connection]
H --> L[Use error message or status]
I --> M[Display User-Friendly Message]
J --> M
K --> M
L --> M
**Diagram sources **
Section sources
WebAuthn Specific Errors
The platform handles several WebAuthn-specific error conditions that arise during registration and authentication flows. These errors are primarily caught at the frontend level and transformed into user-friendly messages. The system distinguishes between different error types to provide appropriate guidance to users.
For registration operations, InvalidStateError indicates that the authenticator is already registered for the account. For authentication, the same error type suggests an authenticator error or invalid credential. NotAllowedError consistently indicates user cancellation or lack of available authenticators across both registration and authentication flows.
flowchart LR
A[WebAuthn Operation] --> B[Check Error Type]
B --> C[NotAllowedError]
C --> D[User cancelled or no authenticator]
B --> E[InvalidStateError]
E --> F[Authenticator already registered]
E --> G[Authenticator error or invalid credential]
B --> H[SecurityError]
H --> I[Connection or security issue]
B --> J[NotSupportedError]
J --> K[WebAuthn not supported in browser]
**Diagram sources **
Section sources
Error Presentation in UI
Errors are presented to users through status indicators in the UI, implemented using the showStatus function from the shared status module. This function displays error messages in a toast-like notification at the bottom of the relevant tab interface. The messages are styled according to their type (error, success, info) and automatically dismiss after a timeout period.
The status system ensures that only one status message is displayed at a time, clearing previous messages when a new one is shown. The position of the status message is adjusted based on the presence of progress indicators, ensuring it remains visible and does not overlap with other interface elements.
flowchart TD
A[Error Occurs] --> B[Call showStatus]
B --> C[Hide Previous Status]
C --> D[Create Status Element]
D --> E[Set Message and Type]
E --> F[Determine Position]
F --> G[Display with Animation]
G --> H[Start Dismiss Timer]
H --> I[Auto-Dismiss After Timeout]
**Diagram sources **
Section sources
Debugging and Troubleshooting
For developers integrating with the API, several common error scenarios require specific troubleshooting approaches. When encountering authentication failures, verify that the username has registered credentials and that the authenticator is properly connected. For registration issues, ensure that the authenticator is not already registered for the account.
Browser compatibility issues can be diagnosed by checking for NotSupportedError, which indicates that WebAuthn is not available in the current browser. Security errors often relate to connection issues or mixed-content restrictions, particularly when serving the application over HTTP instead of HTTPS.
The platform logs credential registration events when enabled, which can assist in debugging issues related to specific authenticators or registration flows. These logs include detailed information about the attestation process and can help identify issues with specific authenticator models or configurations.
Section sources
Conclusion
The Post-Quantum WebAuthn Platform implements a robust error handling system that provides clear feedback to users while maintaining security and usability. By standardizing error responses, transforming low-level errors into user-friendly messages, and providing consistent presentation across the interface, the platform ensures a smooth user experience even when operations fail. The combination of backend validation, frontend error handling, and comprehensive logging creates a solid foundation for debugging and troubleshooting issues that may arise during WebAuthn operations.