token-manager

@visa/token-manager

Visa token generation and management for MCP (Model Context Protocol) authentication.

Overview

This package provides JWE (JSON Web Encryption) token generation, caching, and automatic refresh functionality for authenticating with VIC MCP servers. It handles the complete token lifecycle including credential loading, JWT signing, and JWE encryption.

Features

• 🔐 JWE Token Generation: Creates encrypted tokens using Visa's public keys
• 🔄 Automatic Token Refresh: Manages token expiration and refresh automatically
• 💾 Token Caching: Caches valid tokens to minimize API calls
• ✅ Credential Validation: Uses Zod schemas for robust credential validation
• 🔑 Environment-based Configuration: Loads credentials from environment variables

Installation

This package is designed as a shared utility for the monorepo. It can be used by any project that needs VIC MCP authentication.

For New Projects

To use this package in your project:

1. Add it as a dependency in your package.json:

   {
     "dependencies": {
       "@visa/token-manager": "file:../packages/token-manager"
     }
   }

2. Build the token-manager package:

   cd packages/token-manager
   npm install
   npm run build

3. Install dependencies in your project:

   cd your-project
   npm install

Usage

Basic Usage

import { TokenManager } from '@visa/token-manager';

// Create token manager instance
const tokenManager = new TokenManager();

// Get a valid token (automatically handles caching and refresh)
const token = await tokenManager.getToken();

// Use token for authentication
const headers = {
  Authorization: `Bearer ${token}`,
};

Manual Token Generation

import { createVisaJweToken, loadVisaCredentials } from '@visa/token-manager';

// Load credentials from environment variables
const credentials = loadVisaCredentials();

// Generate a new token
const result = await createVisaJweToken(credentials);
console.log('Token:', result.token);
console.log('Expires at:', result.expiresAt);

Credential Loading

import { loadVisaCredentials } from '@visa/token-manager';

try {
  const credentials = loadVisaCredentials();
  // Credentials are validated and ready to use
} catch (error) {
  console.error('Failed to load credentials:', error.message);
}

Required Environment Variables

The token manager requires the following environment variables:

From Visa Intelligent Commerce Onboarding

Obtained during the Visa Intelligent Commerce onboarding process:

• VISA_VIC_API_KEY - Visa Intelligent Commerce API key
• VISA_VIC_API_KEY_SS - VIC API key shared secret
• VISA_EXTERNAL_CLIENT_ID - External client identifier
• VISA_EXTERNAL_APP_ID - External application identifier

From VTS Onboarding

Obtained during the Visa Token Service onboarding process:

• VISA_VTS_API_KEY - Visa Token Service API key
• VISA_VTS_API_KEY_SS - VTS API key shared secret

MLE Certificates (User Generated)

Can be generated by following the Visa Encryption Guide:

• VISA_MLE_SERVER_CERT - MLE (Message Level Encryption) server certificate
• VISA_MLE_PRIVATE_KEY - MLE private key
• VISA_KEY_ID - Key identifier for MLE

User's JWT Signing Key

Your own private key for signing JWTs (not provided by Visa):

• USER_SIGNING_PRIVATE_KEY - Your RSA private key for JWT signing

Endpoints

• VISA_MCP_BASE_URL - Base URL for Visa MCP server (sandbox or production)

Token Configuration

The token manager uses the following default configuration:

• Token Expiration: 3600 seconds (1 hour)
• Refresh Threshold: 60 seconds before expiry
• Algorithm: RS256 for signing, RSA-OAEP-256 for encryption
• Encryption: A256GCM

Architecture

The token generation process follows these steps:

1. Fetch JWKS: Retrieves Visa's public key from the JWKS endpoint
2. Build JWT Payload: Creates payload with credentials and metadata
3. Sign JWT: Signs the payload using RS256 algorithm
4. Encrypt to JWE: Encrypts the signed JWT using RSA-OAEP-256
5. Cache Token: Stores the token with expiration tracking

Used By

This package is used by:

• @visa/mcp-client - Main MCP client for server communication
• vic-agent/apps/agent - LangGraph agent implementation
• mcp-examples - MCP usage examples and workflow demonstrations
• vic-api-examples - VIC API usage examples
• vdp-api-examples - VDP connectivity testing examples