Token Extraction Utility

Relevant source files

The following files were used as context for generating this wiki page:

• src/extract-token.ts
• src/auth-api.ts
• src/auth-store.ts
• src/index.ts
• tests/auth-api.test.ts

The Token Extraction Utility is a specialized module designed to locate and retrieve access tokens from various JSON response structures returned by authentication services. In the context of the CellarNode authentication system, this utility provides a resilient way to handle different API response schemas, ensuring that tokens can be extracted regardless of whether they are at the root of the response, nested within a data object, or contained within a session object.

This utility is primarily utilized by the AuthApi during the One-Time Password (OTP) verification process and by the AuthStore during automatic token refresh cycles. By centralizing the logic for token identification, the system maintains compatibility with multiple backend response formats while providing a consistent interface for the rest of the application.
Sources: src/extract-token.ts:1-25, src/auth-api.ts:40-45, src/auth-store.ts:25-30

Core Extraction Logic

The utility consists of a single primary function, extractAccessToken, which performs a prioritized search through a provided payload object. It checks for common naming conventions such as accessToken, access_token, and token.

Search Hierarchy

The function inspects the payload in the following order:

1. Root Level: Checks for direct keys in the response object.
2. Data Object: Checks inside a nested data property.
3. Session Object: Checks inside a nested session property.

The following flowchart illustrates the decision-making process within the extraction utility:

The utility ensures that even if backend implementations vary slightly in their JSON structure, the client-side library remains functional.
Sources: src/extract-token.ts:1-25

Integration with Authentication Services

The Token Extraction Utility is a critical dependency for the core authentication workflow. It bridge the gap between raw network responses and the internal state management of the application.

Usage in Auth API

In the verifyOtp method, the API client receives a raw response from the /auth/verify-otp endpoint. The utility is called to parse this response; if no token is found, a TOKEN_EXTRACTION_FAILED error is thrown.

Usage in Auth Store

The AuthStore uses the utility during the performRefresh operation. This allows the store to automatically update the local accessToken when a refresh request to /auth/refresh (or a configured path) succeeds.
Sources: src/auth-store.ts:25-33

Technical Specifications

Extraction Mapping

The utility recognizes specific keys across different object levels:

Level	Keys Searched	Description
Root	accessToken, access_token, token	Direct response fields.
Data	accessToken, access_token	Fields nested within a data object.
Session	accessToken, access_token	Fields nested within a session object.

Sources: src/extract-token.ts:2-22

API Reference

The utility is exported from the main library entry point, allowing for external use or testing.

Function	Parameter	Return Type	Purpose
extractAccessToken	payload: Record<string, unknown>	string | null	Scans an object for valid JWT/access tokens based on predefined patterns.

Sources: src/index.ts:5, src/extract-token.ts:1

Conclusion

The Token Extraction Utility serves as a robust parsing layer within the CellarNode Auth library. By abstracting the variations in token delivery formats, it provides the AuthApi and AuthStore with a reliable mechanism to manage session state, ensuring the system can adapt to different backend response structures without requiring changes to the core authentication logic.