SecPal: Complete LocalStorage Token Removal Guide

Ensuring robust security in web applications requires meticulous attention to detail. This article delves into the process of completely removing localStorage token handling from the SecPal frontend, a crucial step in enhancing security and preventing potential vulnerabilities. We will explore the problem, current behavior, expected behavior, impact, solution, files to modify, acceptance criteria, related issues, and important notes.

The Problem: Lingering localStorage Token Handling

In the realm of web application security, it is crucial to address vulnerabilities promptly and effectively. The initial migration to httpOnly cookies in Epic #208 aimed to bolster security by eliminating the need to store tokens in localStorage. However, despite being marked as complete, the localStorage token handling was not fully eradicated from the SecPal frontend. This oversight left several remnants in the codebase, posing potential security risks and operational challenges. The persistence of these remnants meant that sensitive tokens were still susceptible to XSS attacks, a significant concern for any security-conscious application. Let’s delve deeper into the specific areas where these remnants were found to understand the scope of the problem.

Current Behavior: A Hybrid Authentication System

The current behavior of the SecPal frontend reveals a hybrid authentication system, where both localStorage tokens and httpOnly cookies are in play. This dual approach not only complicates the authentication process but also introduces potential inconsistencies and vulnerabilities. Specifically, the config.ts file's getAuthHeaders() function still actively reads the auth_token from localStorage. This function then sends the token as a Bearer header, which is redundant given the presence of httpOnly cookies. The storage.ts file, while marking token methods as @deprecated, still retains their functionality. This means that these deprecated methods can still be inadvertently used, leading to unexpected behavior. Furthermore, API services continue to utilize getAuthHeaders(), resulting in the transmission of a redundant Authorization header. This not only adds unnecessary overhead but also increases the risk of exposing the token. The following code snippet illustrates the problematic behavior:

// config.ts - STILL ACTIVE
export function getAuthHeaders(): HeadersInit {
 const token = localStorage.getItem("auth_token"); // ❌ Should not exist
 if (token) {
 return { Authorization: `Bearer ${token}` }; // ❌ Redundant with cookies
 }
 return {};
}

Expected Behavior: Secure Cookie-Only Authentication

The expected behavior for the SecPal frontend is a system where authentication is exclusively managed via httpOnly cookies. This approach enhances security by ensuring that no tokens are stored in localStorage, thereby mitigating the risk of XSS attacks. In this ideal scenario, the web SPA (Single Page Application) should authenticate solely through session-based httpOnly cookies. This means that there should be no reliance on localStorage for storing tokens. Consequently, no Authorization: Bearer header should be included in SPA requests, as cookies will handle authentication seamlessly. This transition to a cookie-only authentication system is crucial for maintaining the integrity and security of user sessions and data.

Impact: Security Risks and Operational Challenges

The continued presence of localStorage token handling carries significant implications for the security and operational stability of the SecPal frontend. Understanding these impacts is essential for prioritizing the complete removal of this deprecated mechanism. The following points highlight the key areas of concern:

Security Vulnerabilities: XSS Attacks

The most pressing concern is the security risk posed by storing tokens in localStorage. Tokens stored in localStorage are accessible via Cross-Site Scripting (XSS) attacks. In an XSS attack, malicious scripts injected into a website can access the localStorage and steal the authentication token. This allows attackers to impersonate users and gain unauthorized access to their accounts and data. By removing tokens from localStorage and relying solely on httpOnly cookies, which are not accessible to JavaScript, we significantly reduce the attack surface and enhance the security of the application.

Operational Confusion: Hybrid Authentication

A hybrid authentication system, where both cookies and bearer tokens are used, can lead to confusion and inconsistencies. This approach can cause authentication state mismatches, where the state of the cookie-based authentication differs from the token-based authentication. For instance, a user might have a valid cookie session but an expired token in localStorage, or vice versa. This can result in unpredictable behavior and a degraded user experience. Streamlining the authentication process to use only httpOnly cookies simplifies the system and reduces the likelihood of such mismatches.

Console Errors: Token Expiry Issues

When a hybrid authentication system is in place, discrepancies between token expiry and cookie validity can lead to console errors. For example, if the token stored in localStorage expires while the httpOnly cookie remains valid, the application might attempt to use the expired token, resulting in errors. These errors can clutter the console, making it harder to identify legitimate issues and potentially disrupting the application's functionality. By removing the token-based authentication and relying solely on cookies, we eliminate this source of console errors and improve the overall stability of the application.

Solution: A Step-by-Step Approach to Complete Removal

To address the issues outlined above, a systematic approach is required to completely remove localStorage token handling from the SecPal frontend. This involves several key steps, each targeting a specific aspect of the problem. The following solution outlines the necessary actions to achieve a secure and streamlined authentication process:

1. Remove getAuthHeaders() Function from config.ts

The getAuthHeaders() function in config.ts is responsible for reading the auth_token from localStorage and adding it to the request headers. This function is the primary source of the redundant Authorization header and needs to be removed. By eliminating this function, we prevent the application from attempting to use localStorage tokens for authentication.

2. Remove ...getAuthHeaders() Usage from All API Services

Once the getAuthHeaders() function is removed, all instances where it is used in API services must also be removed. This includes any calls to ...getAuthHeaders() when constructing API requests. Removing these calls ensures that no Authorization header is added based on localStorage tokens.

3. Keep credentials: 'include' for Cookie-Based Auth

To ensure that cookies are included in API requests, the credentials: 'include' option must be maintained. This setting tells the browser to include cookies in cross-origin requests, which is essential for cookie-based authentication. Retaining this setting ensures that the application can seamlessly authenticate users using httpOnly cookies.

4. Mark Token Storage Methods as No-Op (for Backwards Compatibility)

For backwards compatibility, the token storage methods in storage.ts should be marked as no-op. This means that the methods should still exist but perform no operation. This prevents breaking changes in existing code that might be calling these methods. By marking them as no-op, we ensure that any calls to these methods do not result in errors or unexpected behavior.

5. Keep Bearer Token Support in API for Future Native Mobile Apps

It is important to retain Bearer token authentication support in the API backend for future native mobile apps (iOS/Android). Native mobile apps cannot use cookies in the same way as web browsers, so they will require token-based authentication. Maintaining Bearer token support in the API ensures that these apps can authenticate seamlessly.

Files to Modify: Targeted Codebase Adjustments

To implement the solution effectively, specific files within the SecPal frontend codebase need to be modified. These files are directly involved in the localStorage token handling and require targeted adjustments to ensure complete removal. The following files need to be modified:

• src/config.ts: This file contains the getAuthHeaders() function, which needs to be removed.
• src/services/secretApi.ts: This file likely uses getAuthHeaders() in its API calls, and these usages need to be removed.
• src/lib/apiCache.ts: This file may also use getAuthHeaders(), and any instances of its usage should be removed.
• src/services/storage.ts: This file contains the token storage methods that need to be marked as no-op.

Acceptance Criteria: Validating the Solution

To ensure that the solution is correctly implemented and the localStorage token handling is completely removed, specific acceptance criteria must be met. These criteria serve as validation points to confirm that the desired behavior is achieved. The following acceptance criteria must be satisfied:

• No token stored in localStorage after login: After a user logs in, no token should be stored in localStorage. This verifies that the application is not relying on localStorage for token storage.
• No Authorization header in SPA API requests: API requests from the SPA should not include the Authorization header. This confirms that the application is using cookie-based authentication and not sending bearer tokens.
• Authentication works via httpOnly session cookie only: Authentication should function solely through httpOnly session cookies. This ensures that the application is securely authenticating users using cookies.
• All 677+ tests pass: All existing tests must pass to ensure that the changes have not introduced any regressions. This validates the stability and correctness of the application.
• TypeScript strict mode passes: TypeScript strict mode should pass to ensure that the code adheres to strict typing rules. This improves code quality and reduces the likelihood of runtime errors.
• ESLint passes: ESLint should pass to ensure that the code adheres to coding style guidelines. This improves code readability and maintainability.

Related Issues: Contextualizing the Task

This task is closely related to several other issues and epics within the SecPal project. Understanding these relationships provides context and helps ensure that the solution aligns with the overall goals. The following related issues are relevant:

• Epic #208 (Closed as Complete): This epic aimed to migrate to httpOnly cookie authentication. While marked as complete, it did not fully remove localStorage token handling.
• Epic #205 (Closed as Complete): This epic is related to the overall authentication strategy and provides context for the current task.
• api#217 (Backend Epic - Complete): This backend epic focuses on the API aspects of authentication and complements the frontend changes.

Notes: Important Considerations

Several important considerations should be kept in mind while implementing the solution. These notes provide additional context and guidance to ensure a successful outcome. The most crucial point is that Bearer token authentication should remain available in the API backend for future native mobile apps (iOS/Android). These apps cannot use cookies in the same way as web browsers and will require token-based authentication. Therefore, the API must continue to support Bearer token authentication. However, the SPA frontend should exclusively use cookie-based auth, providing a secure and streamlined authentication experience.

By following this comprehensive guide, you can effectively and completely remove localStorage token handling from the SecPal frontend, enhancing security and improving the overall robustness of the application. This meticulous approach ensures that sensitive tokens are protected from potential XSS attacks and that the authentication process is streamlined and secure.

To further enhance your understanding of web application security best practices, consider exploring resources from trusted sources such as the OWASP Foundation. Their comprehensive guides and tools offer valuable insights into securing web applications against various threats.