Vault Auth

A NextJS API package for HashiCorp Vault authentication. This package provides a simple way to authenticate users against your HashiCorp Vault instance and check their policies.

Installation

npm install vault-auth
# or
yarn add vault-auth

Configuration

Set up the following environment variables in your NextJS project:

VAULT_ADDR=https://your-vault-instance.com
VAULT_TOKEN=your-vault-token
VAULT_NAMESPACE=your-namespace  # Optional

These environment variables will be used as the default values but can also be overridden in API calls.

Usage

API Route

The package provides a built-in API route that you can use to authenticate users:

// pages/api/auth.ts
import { VaultAuthService } from 'vault-auth';

// Create with default configuration (will use environment variables)
const vaultAuthService = new VaultAuthService();

export default async function handler(req, res) {
  const { token, requiredPolicy, requiredPolicies, anyPolicy, endpoint, namespace } = req.body;
  
  // Create config from request parameters (will override environment variables)
  const config = {};
  if (endpoint) config.endpoint = endpoint;
  if (namespace) config.namespace = namespace;
  
  // Create service with request-specific configuration
  const serviceWithConfig = new VaultAuthService(config);
  
  // Check for different policy scenarios
  if (requiredPolicy || requiredPolicies) {
    // Use multiple policies if provided, otherwise use single policy
    const policiesToCheck = requiredPolicies || requiredPolicy;
    
    // If anyPolicy is true, check if ANY policy is present
    if (anyPolicy && Array.isArray(requiredPolicies)) {
      const hasAccess = await serviceWithConfig.checkAnyPolicyAccess(token, requiredPolicies);
      return res.status(200).json({ hasAccess });
    } else {
      // Default behavior: check if ALL policies are present
      const hasAccess = await serviceWithConfig.checkPolicyAccess(token, policiesToCheck);
      return res.status(200).json({ hasAccess });
    }
  } else {
    // Just authenticate if no policies specified
    const authResponse = await serviceWithConfig.authenticate(token);
    return res.status(200).json(authResponse);
  }
}

Direct Usage

You can also use the VaultAuthService directly in your code:

import { VaultAuthService } from 'vault-auth';

// Use environment variables
const defaultVaultService = new VaultAuthService();

// Override with custom configuration
const customVaultService = new VaultAuthService({
  endpoint: 'https://custom-vault-instance.com',
  token: 'custom-token',
  namespace: 'custom-namespace' // Optional
});

// Authenticate a token
const authResult = await vaultAuthService.authenticate('user-token');

// Check if a token has access to a specific policy (single policy)
const hasSinglePolicyAccess = await vaultAuthService.checkPolicyAccess('user-token', 'required-policy');

// Check if a token has ALL of the required policies (multiple policies)
const hasAllPoliciesAccess = await vaultAuthService.checkPolicyAccess('user-token', ['policy1', 'policy2', 'policy3']);

// Check if a token has ANY of the required policies
const hasAnyPolicyAccess = await vaultAuthService.checkAnyPolicyAccess('user-token', ['policy1', 'policy2', 'policy3']);

API Reference

VaultAuthService

constructor(config?: VaultConfig)

Creates a new VaultAuthService instance. If no config is provided, environment variables will be used.

authenticate(token: string): Promise

Authenticates a token and returns the associated policies.

checkPolicyAccess(token: string, requiredPolicy: string | string[]): Promise

Checks if a token has access to the required policy or ALL of the required policies if an array is provided.

checkAnyPolicyAccess(token: string, requiredPolicies: string[]): Promise

Checks if a token has access to ANY of the required policies.

Types

interface VaultConfig {
  endpoint?: string;  // Optional, defaults to VAULT_ADDR environment variable
  token?: string;     // Optional, defaults to VAULT_TOKEN environment variable
  namespace?: string; // Optional, defaults to VAULT_NAMESPACE environment variable
}

interface VaultAuthResponse {
  authenticated: boolean;
  policies?: string[];
  error?: string;
}

API Request Format

When making a POST request to the API endpoint, you can use the following format:

{
  "token": "your-vault-token",
  "requiredPolicy": "optional-policy-to-check",
  "requiredPolicies": ["policy1", "policy2", "policy3"],
  "anyPolicy": false,
  "endpoint": "optional-vault-address",
  "namespace": "optional-vault-namespace"
}

• token: (Required) The Vault token to authenticate
• requiredPolicy: (Optional) A single policy to check
• requiredPolicies: (Optional) An array of policies to check
• anyPolicy: (Optional) If true, checks if ANY of the required policies are present; if false (default), checks if ALL required policies are present
• endpoint: (Optional) The Vault endpoint to use
• namespace: (Optional) The Vault namespace to use

License

MIT