npm package: @tadacafe/security
Description: Framework-agnostic security utilities for web applications including HMAC generation, origin validation, and client-side security helpers
Author: TadaCafe
Latest version: 1.0.3

# @tadacafe/security

Framework-agnostic security utilities for web applications including HMAC generation, origin validation, and client-side security helpers.

## Features

- 🔒 **HMAC Generation & Verification** - Cryptographically secure signatures with configurable algorithms
- 🌐 **Origin Validation** - Request origin validation for CORS and CSRF protection
- 🛡️ **Client Security** - Secure form data preparation with timestamps and nonces
- ⏰ **Timestamp Validation** - Prevent replay attacks with configurable time windows
- 🔧 **Framework Agnostic** - Works in Node.js, browsers, and Cloudflare Workers
- 📝 **TypeScript First** - Complete type safety with comprehensive interfaces

## Installation

```bash
npm install @tadacafe/security
```

## Quick Start

### HMAC Operations

```typescript
import { generateHMAC, verifyHMAC } from '@tadacafe/security';

// Generate HMAC signature
const signature = await generateHMAC('my data', {
  secret: 'my-secret-key',
  algorithm: 'SHA-256',
});

// Verify HMAC signature
const isValid = await verifyHMAC('my data', signature, {
  secret: 'my-secret-key',
  algorithm: 'SHA-256',
});
```

### Origin Validation

```typescript
import { isValidOrigin } from '@tadacafe/security';

const isValid = isValidOrigin(request, {
  allowedOrigins: 'https://example.com,https://www.example.com',
  allowRefererFallback: true,
  enableDebugLogging: true,
});

if (!isValid) {
  return new Response('Forbidden', { status: 403 });
}
```

### Secure Form Data

```typescript
import { prepareSecureFormData } from '@tadacafe/security';

const secureData = await prepareSecureFormData(
  { name: 'John', email: 'john@example.com' },
  { formSecret: 'my-secret-key' }
);

// Result includes original data plus timestamp, nonce, and hmac
console.log(secureData);
// {
//   name: 'John',
//   email: 'john@example.com',
//   timestamp: 1634567890123,
//   nonce: 'a1b2c3d4e5f6789012345678901234567890abcd',
//   hmac: '...'
// }
```

## API Reference

### Cryptographic Functions

#### `generateNonce(length?: number): string`

Generate a cryptographically secure nonce.

- **length**: Length of the nonce in bytes (default: 16)
- **Returns**: Hexadecimal string representation of the nonce

#### `generateHMAC(data: string, config: HMACConfig): Promise<string>`

Generate HMAC signature for data.

- **data**: The data to sign
- **config**: HMAC configuration
- **Returns**: Promise resolving to hexadecimal HMAC signature

#### `verifyHMAC(data: string, hmac: string, config: HMACConfig): Promise<boolean>`

Verify HMAC signature using constant-time comparison.

- **data**: The original data that was signed
- **hmac**: The HMAC signature to verify
- **config**: HMAC configuration
- **Returns**: Promise resolving to verification result

#### `isValidTimestamp(timestamp: number, config?: TimestampValidationConfig): boolean`

Validate request timestamp to prevent replay attacks.

- **timestamp**: The timestamp to validate (in milliseconds)
- **config**: Configuration for timestamp validation
- **Returns**: True if timestamp is valid

### Origin Validation Functions

#### `isValidOrigin(request: Request, config: OriginValidationConfig): boolean`

Validate request origin against allowed origins list.

- **request**: The incoming HTTP request
- **config**: Origin validation configuration
- **Returns**: True if request origin is valid

#### `isValidOriginFromEnv(request: Request, options?): boolean`

Convenience function for validating origin using environment variables configured in options or process environment.
- **options**: (Optional) Additional options or overrides for environment-based configuration
- **Returns**: True if request origin is valid based on environment configuration

### Client Security

#### `prepareSecureFormData<T>(formData: T, config: SecureFormConfig): Promise<T & SecuredFormData>`

Prepare secure form data by adding timestamp, nonce, and HMAC signature.

#### `createSecureFormPreparer(defaultConfig: SecureFormConfig): Function`

Create a reusable secure form preparation function with pre-configured settings.

#### `getFormSecret(sources: object, fallback?: string): string`

Utility to resolve form secret from various sources with fallback.

## Configuration Interfaces

### `HMACConfig`

```typescript
interface HMACConfig {
  secret: string;
  algorithm?: 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512'; // default: 'SHA-256'
}
```

### `OriginValidationConfig`

```typescript
interface OriginValidationConfig {
  allowedOrigins: string | string[];
  allowRefererFallback?: boolean; // default: true
  enableDebugLogging?: boolean; // default: false
}
```

### `TimestampValidationConfig`

```typescript
interface TimestampValidationConfig {
  maxAgeMinutes?: number; // default: 10
  maxClockSkewMs?: number; // default: 60000 (1 minute)
}
```

### `SecureFormConfig`

```typescript
interface SecureFormConfig {
  formSecret: string;
  hmacConfig?: Omit<HMACConfig, 'secret'>;
}
```

## Environment Support

This package works in multiple environments:

- **Node.js**: Full support for all features
- **Browser**: Full support with Web Crypto API
- **Cloudflare Workers**: Full support in Worker runtime
- **Vite/Webpack**: Compatible with modern bundlers

## Security Best Practices

### HMAC Secrets

- Use cryptographically strong secrets (minimum 32 characters)
- Store secrets securely (environment variables, secret managers)
- Rotate secrets regularly
- Never expose secrets in client-side code

### Origin Validation Best Practices

- Always validate origins for sensitive operations
- Use HTTPS origins only in production
- Consider both Origin and Referer headers for maximum compatibility
- Enable debug logging in development, disable in production

### Timestamp Validation

- Use reasonable time windows (5-10 minutes)
- Account for clock skew between client and server
- Implement proper time synchronization
- Log suspicious timestamp patterns

## Usage Examples

### Cloudflare Workers

```typescript
import {
  isValidOriginFromEnv,
  verifyHMAC,
  isValidTimestamp,
} from '@tadacafe/security';

export default {
  async fetch(request, env) {
    // Validate origin
    if (!isValidOriginFromEnv(request, env, { enableDebugLogging: true })) {
      return new Response('Forbidden', { status: 403 });
    }

    // Parse and verify form data
    const data = await request.json();
    const { timestamp, nonce, hmac, ...formData } = data;

    // Validate timestamp
    if (!isValidTimestamp(timestamp, { maxAgeMinutes: 10 })) {
      return new Response('Request expired', { status: 400 });
    }

    // Verify HMAC
    const dataToVerify = JSON.stringify({ ...formData, timestamp, nonce });
    const isValidHMAC = await verifyHMAC(dataToVerify, hmac, {
      secret: env.CONTACT_FORM_SECRET,
    });

    if (!isValidHMAC) {
      return new Response('Invalid signature', { status: 400 });
    }

    // Process valid request...
  },
};
```

### React Component

```typescript
import { prepareSecureFormData, getFormSecret } from '@tadacafe/security';

function ContactForm() {
  const handleSubmit = async (formData) => {
    const formSecret = getFormSecret({
      vite: import.meta.env.VITE_CONTACT_FORM_SECRET,
    });

    const secureData = await prepareSecureFormData(formData, { formSecret });

    const response = await fetch('/api/contact', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(secureData),
    });
  };
}
```

## License

MIT