TokenGuardian

🔒 Zero-trust token security, leak prevention and rotation automation for Node.js applications

The Problem

API tokens, JWT tokens, and secrets are constantly leaked through accidental commits, environment misconfigurations, and poor rotation practices. Once exposed, these tokens create significant security vulnerabilities that often go undetected until it's too late.

The Solution

TokenGuardian provides multi-layered protection for your tokens and secrets:

1. Leak Prevention - Git pre-commit hooks that scan for potential token patterns across multiple formats
2. Validation - Runtime token validation that verifies entropy and format compliance
3. Rotation - Fully automated token rotation capabilities with common services (AWS, GitHub, etc.)
4. Monitoring - Token canary system that alerts when exposed credentials are used
5. Tracking - Fingerprinting to track token usage across systems

Installation

npm install token-guardian

For default JWT rotation, set an explicit signing secret before using the built-in default rotator:

export TOKEN_GUARDIAN_SECRET_KEY="$(openssl rand -hex 32)"

Usage

import { TokenGuardian } from 'token-guardian';

// Initialize TokenGuardian with your configuration
const guardian = new TokenGuardian({
  services: ['github', 'aws'],
  rotationInterval: '7d',
  canaryEnabled: true
});

// Check if a string contains potential tokens or secrets
const hasSensitiveData = guardian.scanString('My API key is sk_test_1234567890abcdef');

// Protect your GitHub token. PAT rotation is intentionally disabled because
// GitHub does not expose supported APIs for PAT create/delete operations.
guardian.protect('GITHUB_TOKEN', process.env.GITHUB_TOKEN, {
  rotationEnabled: false,
  canaryEnabled: true,
  serviceType: 'github'
});

// Protect your AWS credentials and enable rotation
// AWS credentials must be in format "ACCESS_KEY_ID:SECRET_ACCESS_KEY"
guardian.protect('AWS_CREDENTIALS', `${process.env.AWS_ACCESS_KEY_ID}:${process.env.AWS_SECRET_ACCESS_KEY}`, {
  rotationEnabled: true,
  canaryEnabled: true,
  serviceType: 'aws'
});

// Get a protected token
const token = guardian.getToken('GITHUB_TOKEN');

// Manually rotate a token
await guardian.rotateToken('AWS_CREDENTIALS');

// Pause scheduled rotation if you need to take a token out of circulation temporarily
guardian.stopRotation('GITHUB_TOKEN');

// Stop all scheduled rotations (useful during shutdown or maintenance)
guardian.stopAllRotations();

Features

🔍 Token Detection

TokenGuardian can detect over 150 different token formats, including:

• API Keys (AWS, GitHub, Stripe, etc.)
• JWT Tokens
• OAuth Tokens
• Private Keys (SSH, RSA, etc.)
• Cryptocurrency Private Keys
• Database Connection Strings

🔄 Automated Rotation

TokenGuardian provides actual working rotation for supported services:

• AWS IAM Keys: Securely rotates IAM access keys with proper verification AWS IAM responses are validated against the expected result blocks before new key material is accepted.
• GitHub Tokens: PAT rotation is disabled by design; use OAuth refresh tokens or GitHub App credentials instead
• Default JWT Rotation: Requires an explicit TOKEN_GUARDIAN_SECRET_KEY; no insecure fallback secret is used
• Custom Services: Extensible framework for adding more services
• Rotation Controls: Explicitly pause rotation per token or stop all schedules during shutdown

Rotation intervals are validated (positive integers followed by d, h, m, or s). Invalid inputs automatically fall back to the configured default (30d by default).

🕵️ Canary Tokens

Embed undetectable canary markers in your tokens to be alerted when they're used outside your authorized systems. Supports clever embedding in:

• Long string tokens (minimal modifications that maintain functionality)
• Multiple format-specific strategies for optimal tracking

JWTs are left unchanged to preserve signature validity; TokenGuardian does not mutate signed JWT payloads for canary tracking. Webhook and per-token alert endpoints must use https:// and cannot point at localhost or private-network IP literals.

🔐 Token Storage

All sensitive data is encrypted at rest using AES-256-GCM authenticated encryption with:

• Per-token encryption to minimize exposure
• Secure key derivation
• Tamper detection on decrypt
• Comprehensive audit logging

🌐 Token Fingerprinting

Track where and how your tokens are being used across your infrastructure:

• Usage patterns
• Access timestamps
• Anomaly detection

CI/CD and GitHub Workflows

To use the included CI/CD workflows, copy the workflow files into your GitHub repository:

1. Create the .github/workflows directory
2. Copy ci-workflow.yml to .github/workflows/ci.yml
3. Copy release-workflow.yml to .github/workflows/release.yml

These workflows will:

• Run tests on multiple Node.js versions
• Perform security scanning with CodeQL
• Publish releases to npm

Security

TokenGuardian takes a zero-trust approach to token security. All sensitive data is encrypted at rest and in transit, and we implement defense-in-depth with multiple layers of protection. Operational logs redact common secret-bearing fields such as tokens, authorization headers, API keys, and client secrets.

License

MIT