Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the execution flow when a user initiates the download of task evidence from the SingleTask component, leading to the decoding of a JSON Web Token (JWT) payload. The primary goal of this process is to securely fetch a file from the backend API, which requires a valid authentication token.
The flow begins with a user interaction in the SingleTask UI, triggering a file download. To ensure the request is authenticated, the system relies on a jwtManager utility. This utility is responsible for providing a valid JWT, proactively refreshing it if it's missing or nearing expiration. A crucial part of this refresh mechanism involves decoding the JWT's payload to extract its expiration timestamp, thereby allowing the system to manage token validity and schedule future refreshes efficiently. This ensures that authenticated operations, like downloading sensitive evidence, proceed seamlessly without requiring the user to re-authenticate frequently.
1. User Initiates Evidence Download
The process begins within the SingleTask React component when a user clicks the "Download task evidence" button. This action triggers an asynchronous operation to fetch a ZIP archive containing all evidence related to the current task. The component catches potential errors during the download and provides user feedback via toast notifications.
The SingleTask component is responsible for rendering the task details and providing interactive elements, including the download button for task evidence.
Source: apps/app/src/app/(app)/[orgId]/tasks/[taskId]/components/SingleTask.tsx:196-209
2. Prepare Task Evidence Download
Upon the user's action, the downloadTaskEvidenceZip function is called. This function is part of the evidence-download utility library and is responsible for constructing the correct API endpoint for the task evidence ZIP file. It takes the taskId, taskTitle, organizationId, and an includeJson flag as parameters. It then delegates the actual download operation to a more generic downloadFile function.
Inputs:
taskId: The ID of the task for which evidence is being downloaded.taskTitle: The title of the task, used for generating a user-friendly filename.organizationId: The ID of the organization, required for API calls.includeJson: A boolean indicating whether to include JSON metadata in the ZIP.
Output: A call to downloadFile with the constructed URL and metadata.
Source: apps/app/src/lib/evidence-download.ts:46-60
3. Execute File Download with Authentication
The downloadFile function, also within the evidence-download utility, handles the core logic of fetching a file from a given URL. Before making the fetch request, it prepares the necessary HTTP headers, including the X-Organization-Id. Crucially, it attempts to retrieve a valid JWT token for authentication. If successful, this token is added to the Authorization header as a Bearer token. The function then performs the fetch request, handles potential HTTP errors, extracts the filename from the Content-Disposition header (or generates a fallback), and finally initiates the client-side download by creating a temporary <a> element.
Inputs:
url: The full API endpoint for the file to be downloaded.organizationId: The organization ID for theX-Organization-Idheader.fallback: An optional object containingfallbackBaseNameandfallbackExtensionfor filename generation.
Data Flow:
- Calls
jwtManager.getValidToken()to obtain an authentication token. - Constructs
headersobject withX-Organization-IdandAuthorization(if token is available). - Performs
fetch(url, { method: 'GET', headers, credentials: 'include' }). - Processes
response.blob()andContent-Dispositionheader to get the file and its name.
Error Handling:
- If
jwtManager.getValidToken()fails, an error is logged, and a new error "Authentication failed" is thrown. - If the
fetchresponse is notok, an error is thrown with the response text or status.
Source: apps/app/src/lib/evidence-download.ts:98-145
4. Retrieve a Valid JWT Token
The jwtManager.getValidToken() method is invoked to ensure that any outgoing API request is authenticated with a current and valid JWT. It first checks if a token is already stored in localStorage and if that token is still valid or not expiring soon (within a REFRESH_THRESHOLD of 5 minutes).
Branching Logic:
- If a stored token exists and is not expiring soon: The method logs "✅ Using cached JWT token" and returns the stored token immediately.
- If no token is stored or the stored token is expiring soon: The method logs "🔄 JWT token missing or expiring soon, fetching fresh token..." and proceeds to call
this.refreshToken()to acquire a new token.
Error Handling:
- If any error occurs during this process, it's logged, and
nullis returned, indicating that no valid token could be obtained.
Source: apps/app/src/utils/jwt-manager.ts:25-40
5. Orchestrate Token Refresh
The jwtManager.refreshToken() method is responsible for managing the token refresh process. It includes logic to prevent multiple concurrent refresh attempts and enforces a cooldown period between refreshes to avoid overwhelming the authentication service.
Concurrency and Cooldown:
- It checks
this.refreshPromise: If a refresh is already in progress, it waits for that existing promise to resolve. - It checks
this.lastRefreshAttemptandREFRESH_COOLDOWN: If a refresh was attempted too recently, it waits for the cooldown period to pass. During this wait, if a valid token is already available, it might return that token.
Once these checks pass, it records the lastRefreshAttempt and sets this.refreshPromise to the result of this._doRefreshToken(), ensuring that subsequent calls wait for this refresh to complete.
Output: Returns the new token obtained from _doRefreshToken or null if the refresh fails.
Source: apps/app/src/utils/jwt-manager.ts:47-79
6. Perform Actual Token Refresh
The jwtManager._doRefreshToken() method executes the actual network requests to obtain a new JWT. It attempts two primary strategies:
- Session-based refresh: It first tries to get a JWT from the
authClient.getSession()call. TheonSuccesscallback inspects the response headers for aset-auth-jwtheader. - Explicit token endpoint: If the session-based approach doesn't yield a token, it makes a direct
fetchrequest to the/api/auth/tokenendpoint.
Data Flow:
- Sends requests to authentication endpoints.
- Receives a
newTokenstring if successful.
Subsequent Actions:
- If a
newTokenis successfully acquired, it callsthis.storeToken(newToken)to save the new token and its expiry. - It then calls
this.scheduleRefresh(newToken)to set up an automatic refresh before the new token expires.
Error Handling:
- Logs warnings if the token endpoint fails.
- Logs errors if the overall refresh process fails and returns
null.
Source: apps/app/src/utils/jwt-manager.ts:86-128
7. Store New Token and Expiry
The jwtManager.storeToken() method is responsible for persisting the newly acquired JWT and its expiration timestamp in localStorage. This allows the application to retrieve the token quickly for subsequent authenticated requests without needing to refresh it every time.
Data Flow:
- Takes the
tokenstring as input. - Calls
this.decodeJWTPayload(token)to extract the expiration time (exp) from the token's payload. - Stores the
tokenunderthis.STORAGE_KEYand theexpiresAt(converted to milliseconds) underthis.EXPIRY_KEYinlocalStorage.
Error Handling:
- Catches and logs any errors that occur during the storage process, particularly if
decodeJWTPayloadfails.
Source: apps/app/src/utils/jwt-manager.ts:135-146
8. Decode JWT Payload
The jwtManager.decodeJWTPayload() method is a utility function used to parse the base64-encoded payload of a JWT. This is a client-side operation and does not involve cryptographic verification, as its purpose is simply to extract information like the expiration timestamp (exp) for local token management.
Inputs:
token: The full JWT string.
Process:
- Splits the JWT into its three parts (header, payload, signature) by the
.delimiter. - Takes the second part (the payload).
- Uses
atob()to base64-decode the payload string. - Parses the resulting string as JSON.
Output: The parsed JSON object representing the JWT payload.
Error Handling:
- If the token format is invalid (e.g., not enough parts, or base64 decoding/JSON parsing fails), it throws an
Error('Invalid JWT token format').
Source: apps/app/src/utils/jwt-manager.ts:170-177
Sequence Diagram
Flowchart
Key Observations
- Cross-Module Boundaries: This flow demonstrates clear separation of concerns across different modules:
SingleTask.tsx: Handles UI interaction and initiates the high-level action.evidence-download.ts: Manages the specifics of file downloading, including API endpoint construction and client-side download mechanics.jwt-manager.ts: Centralizes all JWT-related operations, such as token retrieval, refresh, storage, and decoding, abstracting authentication details from the download logic.
- Potential Failure Points and Handling:
- Authentication Failure: If
jwtManager.getValidToken()or_doRefreshToken()fails to acquire a token, thedownloadFilefunction will throw an "Authentication failed" error, which is then caught bySingleTaskand displayed as atoast.error. - Network Errors:
fetchrequests indownloadFileand_doRefreshTokencan fail due to network issues or API unavailability. These are caught and reported to the user viatoast.error. - Invalid JWT Format:
decodeJWTPayloadexplicitly checks for valid JWT structure and throws an error if parsing fails, preventing corrupted tokens from being used. - Concurrent Refreshes: The
jwtManagerusesrefreshPromiseandREFRESH_COOLDOWNto prevent multiple token refresh requests from being sent simultaneously, which could lead to race conditions or unnecessary load on the authentication service.
- Authentication Failure: If
- Performance Considerations:
- Token Caching: JWTs are stored in
localStorageand reused, reducing the need for frequent authentication requests. - Proactive Refresh: The
scheduleRefreshmechanism attempts to refresh the token a few minutes before its actual expiration (REFRESH_THRESHOLD), ensuring that a valid token is usually available when an API call is made, minimizing latency for authenticated requests. - Optimistic Refresh: The
refreshTokenmethod's handling ofrefreshPromisemeans that if multiple parts of the application simultaneously request a token refresh, only one actual refresh operation is performed, and all callers await its result.
- Token Caching: JWTs are stored in
On This Page
1. User Initiates Evidence Download2. Prepare Task Evidence Download3. Execute File Download with Authentication4. Retrieve a Valid JWT Token5. Orchestrate Token Refresh6. Perform Actual Token Refresh7. Store New Token and Expiry8. Decode JWT PayloadSequence DiagramFlowchartKey Observations