🔒 Enhanced Validation Guards & Token Confusion Prevention

Critical security release adding token confusion attack prevention and configurable security settings.

🛡️ Security Improvements

Token Confusion Attack Prevention:

• Strict issuer validation prevents tokens from wrong tenant/cloud
• Automatic detection of commercial vs government cloud mismatches
• Validates tenant ID matches expected value
• Clear error messages indicating exact mismatch

Example Attack Prevented:

// Attacker obtains token from their Azure AD tenant
// Tries to use it in your application
// ❌ Latch now rejects with clear error:
// "Token issuer mismatch (potential token confusion attack)"

🆕 New Features

1. validateIssuer() Helper:

import { validateIssuer } from '@lance0/latch';

// Validate token issuer matches expectations
validateIssuer(payload.iss, config.tenantId, config.cloud);

2. Enhanced verifyIdToken():

const user = await verifyIdToken(
  tokens.id_token,
  endpoints.jwksUri,
  config.clientId,
  pkceData.nonce,
  {
    tenantId: config.tenantId,  // Validates correct tenant
    cloud: config.cloud,         // Validates correct cloud
    clockTolerance: 60,          // Configurable clock skew
  }
);

3. Configurable Security Settings:

# Clock skew tolerance for token validation
LATCH_CLOCK_SKEW_TOLERANCE=60    # default: 60 seconds

# JWKS cache TTL
LATCH_JWKS_CACHE_TTL=3600         # default: 1 hour

📚 Security Documentation

Updated SECURITY.md:

• New section: Token Confusion Attack Prevention
• Attack scenarios and protections explained
• Code examples and best practices
• Multi-tenant security guidance

Attack Scenarios Prevented:

• Multi-tenant apps accepting tokens from wrong tenant
• Apps misconfigured for wrong cloud (commercial vs government)
• Token replay from different tenant
• Cross-cloud token confusion

🧪 Tests

• 19 new security tests for issuer validation
• Multi-tenant scenario coverage
• Token confusion attack scenarios
• 161 total tests passing

📦 Installation

npm install @lance0/latch@0.4.1

🔄 Migration

Breaking Changes: None

Recommended (Optional):
Update your callback route to enable enhanced validation:

const user = await verifyIdToken(
  tokens.id_token,
  endpoints.jwksUri,
  config.clientId,
  pkceData.nonce,
  {
    tenantId: config.tenantId,  // Add this
    cloud: config.cloud,         // Add this
  }
);

This is optional but strongly recommended for multi-tenant applications or government cloud deployments.

📊 Roadmap Progress

✅ Completed: Enhanced Validation Guards (High Priority)

Remaining for v1.0:

1. Example App Presets (2-3 hours)
2. Migration Guides (2-3 hours)
3. Security Audit (external)

🔗 Links

• SECURITY.md - Full security documentation
• npm Package
• Changelog

Security Note: This release hardens Latch against token confusion attacks, a class of vulnerability where applications accept tokens from unintended issuers. All users should upgrade.