@nibssplc/cams-sdk/README.md

Central Authentication Management Service (CAMS) SDK for popup-based authentication with Azure AD + custom 2FA

# NIBSS CAMS SDK

Central Authentication Management Service (CAMS) SDK for popup-based authentication with Azure AD + custom 2FA.

## Features

- 🔐 Secure popup-based authentication
- 🛡️ URL validation and domain allowlisting
- ⏱️ Configurable timeouts and retry logic
- 🔄 Automatic token management with expiration checking
- 📱 Session management with event callbacks
- 🧪 Comprehensive TypeScript support
- ✅ Full test coverage

## Installation

```bash
npm install @nibssplc/cams-sdk
```

## Quick Start

### Basic Usage

```typescript
import { openCAMSLogin, CAMSConfig } from '@nibssplc/cams-sdk';

const config: CAMSConfig = {
  camsUrl: 'https://your-cams-instance.com/auth',
  allowedOrigin: 'https://your-cams-instance.com',
  windowWidth: 500,
  windowHeight: 600,
  timeout: 300000, // 5 minutes
  allowedDomains: ['your-cams-instance.com'], // Security allowlist
  debug: true, // Enable debug logging
};

try {
  const response = await openCAMSPopUpLogin(config);
  console.log('Authentication successful:', response.token);
} catch (error) {
  console.error('Authentication failed:', error);
}
```

### Session Management (Recommended)

```typescript
import { CAMSSessionManager, CAMSEvents } from '@nibssplc/cams-sdk';

const events: CAMSEvents = {
  onAuthStart: () => console.log('Authentication started'),
  onAuthSuccess: (token) => console.log('Login successful'),
  onAuthError: (error) => console.error('Login failed:', error),
  onTokenExpired: () => console.log('Token expired'),
};

const session = new CAMSSessionManager(sessionStorage, 'my_app_token', events);

// Login with retry logic
const config = {
  // ... your config
  retryAttempts: 2, // Retry twice on failure
};

try {
  await session.login(config);
  
  // Check authentication status
  if (session.isAuthenticated()) {
    const token = session.getAccessToken();
    const profile = await session.getProfile();
  }
} catch (error) {
  // Handle authentication error
}

// Logout
await session.logout();
```

## Configuration Options

```typescript
interface CAMSConfig {
  camsUrl: string;           // CAMS authentication URL
  allowedOrigin: string;     // Expected message origin
  windowWidth: number;       // Popup window width
  windowHeight: number;      // Popup window height
  timeout?: number;          // Auth timeout in ms (default: 300000)
  allowedDomains?: string[]; // URL allowlist for security
  storageKey?: string;       // Custom storage key
  retryAttempts?: number;    // Auto-retry on failure (default: 0)
  debug?: boolean;           // Enable debug logging (default: false)
}
```

## Error Handling

The SDK provides typed errors for better error handling:

```typescript
import { CAMSError, CAMSErrorType } from '@nibssplc/cams-sdk';

try {
  await session.login(config);
} catch (error) {
  if (error instanceof CAMSError) {
    switch (error.type) {
      case CAMSErrorType.POPUP_BLOCKED:
        // Handle popup blocker
        break;
      case CAMSErrorType.TIMEOUT:
        // Handle timeout
        break;
      case CAMSErrorType.INVALID_URL:
        // Handle invalid URL
        break;
      case CAMSErrorType.USER_CANCELLED:
        // Handle user cancellation
        break;
    }
  }
}
```

## Security Features

- **URL Validation**: Prevents open redirect attacks
- **Domain Allowlisting**: Restricts authentication to approved domains
- **Origin Validation**: Validates message origins
- **Token Validation**: Uses Zod schemas for runtime validation
- **Secure Storage**: Configurable storage with automatic cleanup

## Debugging

The SDK includes comprehensive logging to aid in debugging:

```typescript
import { Logger, LogLevel } from '@nibssplc/cams-sdk';

// Set global log level
Logger.setLevel(LogLevel.DEBUG);

// Or enable debug mode in config
const config = {
  // ... other config
  debug: true // Automatically sets debug level
};
```

**Log Levels:**
- `ERROR`: Critical errors only
- `WARN`: Warnings and errors (default)
- `INFO`: General information, warnings, and errors
- `DEBUG`: All logs including detailed flow information

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Lint
npm run lint
```

## License

MIT © NIBSS PLC