ADRs: 012-016 - Adding Impact Sections

[tjohnson7021]

Description

This PR covers filling in the impact sections for ADRs 012-016 so that it is understood why the decision was made at the time and what the concerns were.

This PR errs on the side of being more verbose than not so that unneeded items can be stripped away during review, so please read carefully.

NOTE: a change to ADR 001 was added to this PR to make linking work better in the IDE.

Issue #1247

Checklist

• I have updated the documentation accordingly

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ✅ 1247 - Fully compliant Fully compliant requirements: Completed the "Impact" section for ADRs 012-016.

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Complexity Concern The added complexity due to the AuthN/AuthZ layers might need further review to ensure it does not overly complicate the system. Wrapper Design The design of the wrapper interface should be reviewed to ensure it does not limit flexibility or create tight coupling with specific implementations.

[github-actions]

Consider reducing the verbosity of the Impact section by summarizing the key points more succinctly. This will help maintain the readability and focus of the document. [important]

[github-actions]

It might be beneficial to add specific examples or case studies that demonstrate the positive impacts mentioned, such as how the decoupling has concretely improved maintainability in past projects. [medium]

[github-actions]

To address the risk of human error in implementation, consider recommending specific tools or automated checks that can enforce the naming conventions consistently across the project. [important]

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Score
Possible issue	Implement error handling for JWT validation to enhance security and stability Add error handling for JWT validation failures to prevent unauthorized access and ensure system stability. adr/012-auth.md [24] -3. We validate that the JWT is valid given the public key they sent to us earlier. +3. We validate that the JWT is valid given the public key they sent to us earlier, implementing error handling to manage validation failures securely. Suggestion importance[1-10]: 8 Why: Adding error handling for JWT validation failures is crucial for security and system stability, preventing unauthorized access and ensuring the system can gracefully handle errors.	8
General	Use automation to enforce the new key naming convention and manage key migrations Implement automated tools or scripts to enforce the new naming convention and manage the migration of existing keys to reduce human error. adr/014-keys.md [29] -This naming convention applies to all locations where our keys are stored. +This naming convention applies to all locations where our keys are stored, enforced through automated tools or scripts to ensure consistency and manage the migration of existing keys. Suggestion importance[1-10]: 8 Why: Implementing automated tools to enforce naming conventions and manage key migrations reduces the risk of human error and ensures consistency across the system, which is crucial for security and operational efficiency.	8
	Design the wrapper interface to be adaptable to changes in the third-party library Ensure that the wrapper interface is designed to be flexible enough to accommodate changes in the underlying third-party library without significant rework. adr/013-wrapped-domain-objects.md [17] -The implementation of this interface is customized to use the underlying third party library. +The implementation of this interface is customized to use the underlying third party library, designed with flexibility to adapt to changes in the third-party library with minimal rework. Suggestion importance[1-10]: 6 Why: The suggestion to design the wrapper interface with flexibility enhances maintainability and adaptability, allowing easier updates or changes to the third-party library with minimal impact on the system.	6
Security	Enhance the security of JWT tokens by ensuring encryption and secure transmission Ensure that the JWT tokens are properly encrypted and securely transmitted to prevent interception and misuse. adr/012-auth.md [7] -We will use an AuthN/AuthZ concept similar to ReportStream's "two legged" auth. This model uses JSON Web Tokens (JWT) for secure client authentication and authorization across API interactions. +We will use an AuthN/AuthZ concept similar to ReportStream's "two legged" auth. This model uses encrypted JSON Web Tokens (JWT) for secure client authentication and authorization across API interactions, ensuring tokens are securely transmitted. Suggestion importance[1-10]: 7 Why: The suggestion to ensure encryption and secure transmission of JWT tokens directly addresses a critical security aspect of authentication mechanisms, enhancing the security posture of the system.	7

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud