Token Cache Service

A token management service that provides caching and automatic refresh capabilities for authentication tokens used with Azure services.

Problem Description

You need to implement a token cache service that manages authentication tokens efficiently. The service should store tokens in memory, handle automatic refresh based on expiration times, and support multiple scope configurations.

Requirements

Token Storage

The service must maintain an in-memory cache of authentication tokens, keyed by scope. When multiple scopes are requested together, they should be cached under a normalized key (e.g., sorted and joined scope strings).

Token Retrieval

When a token is requested:

• If a valid cached token exists and has not expired, return it immediately
• If a cached token exists but should be refreshed (based on refresh timestamp), obtain a fresh token and update the cache
• If no cached token exists or the token has expired, obtain a new token from the credential and cache it
• Handle both single scope strings and arrays of scopes

Token Expiration

Tokens should be considered expired when the current time exceeds their expiration timestamp. The service should proactively refresh tokens when the current time exceeds their refresh-after timestamp (if provided).

Error Handling

• Return null if token retrieval fails from the underlying credential
• Handle cases where credentials return null gracefully
• Validate that required scope parameters are provided

Implementation

@generates

API

import { TokenCredential, AccessToken } from "@azure/core-auth";

/**
 * TokenCacheService manages token caching and automatic refresh.
 */
export class TokenCacheService {
  /**
   * Creates a new TokenCacheService.
   * @param credential - The credential to use for obtaining tokens
   */
  constructor(credential: TokenCredential);

  /**
   * Gets a token for the specified scope(s), using cache when available.
   * @param scopes - A single scope string or array of scope strings
   * @returns A promise that resolves to an access token or null
   */
  getToken(scopes: string | string[]): Promise<AccessToken | null>;

  /**
   * Clears all cached tokens.
   */
  clearCache(): void;

  /**
   * Clears cached token for specific scope(s).
   * @param scopes - A single scope string or array of scope strings
   */
  clearCacheForScope(scopes: string | string[]): void;
}

Test Cases

Basic Token Caching

• When requesting a token for a scope that hasn't been cached, it calls the underlying credential and caches the result @test
• When requesting a token for a scope that has been cached and is still valid, it returns the cached token without calling the credential @test
• When requesting a token for multiple scopes as an array, it normalizes the scope key and caches appropriately @test

Token Refresh

• When a cached token has expired (current time exceeds expiration timestamp), it obtains a new token from the credential @test
• When a cached token has a refresh-after timestamp that has been exceeded but not expired, it obtains a fresh token from the credential @test

Cache Management

• The clearCache method removes all cached tokens @test
• The clearCacheForScope method removes only the cached token for the specified scope(s) @test

Error Handling

• When the underlying credential returns null, the service returns null without caching @test

Dependencies { .dependencies }

@azure/core-auth { .dependency }

Provides token authentication interfaces and types for Azure services.

@satisfied-by