smartradius/ts_client/readme.md

# @push.rocks/smartradius/client

> 📱 RADIUS Client Implementation - Connect to RADIUS servers with PAP, CHAP, and accounting support

## Overview

This module provides a RADIUS client implementation for connecting to RADIUS servers. It supports PAP and CHAP authentication methods, accounting operations, and includes automatic retry with exponential backoff.

## Features

- ✅ **PAP Authentication** - Password Authentication Protocol
- ✅ **CHAP Authentication** - Challenge-Handshake Authentication Protocol
- ✅ **Accounting** - Session start, stop, and interim updates
- ✅ **Automatic Retries** - Configurable retry count with exponential backoff
- ✅ **Timeout Handling** - Per-request timeouts
- ✅ **Custom Attributes** - Support for adding custom RADIUS attributes
- ✅ **Response Validation** - Authenticator verification for security

## Exports

### Classes

| Class | Description |
|-------|-------------|
| `RadiusClient` | Main client class for RADIUS operations |

### Interfaces (Client-Specific)

| Interface | Description |
|-----------|-------------|
| `IRadiusClientOptions` | Client configuration options |
| `IClientAuthRequest` | Authentication request parameters |
| `IClientAuthResponse` | Authentication response from server |
| `IClientAccountingRequest` | Accounting request parameters |
| `IClientAccountingResponse` | Accounting response from server |

## Usage

### Basic Authentication

```typescript
import { RadiusClient } from '@push.rocks/smartradius';

const client = new RadiusClient({
  host: '192.168.1.1',
  secret: 'shared-secret',
  timeout: 5000,
  retries: 3,
});

await client.connect();

// PAP Authentication
const papResult = await client.authenticatePap('username', 'password');
if (papResult.accepted) {
  console.log('Login successful!');
  console.log('Session timeout:', papResult.sessionTimeout);
}

// CHAP Authentication
const chapResult = await client.authenticateChap('username', 'password');
if (chapResult.accepted) {
  console.log('CHAP login successful!');
}

await client.disconnect();
```

### Accounting

```typescript
import { RadiusClient, EAcctStatusType } from '@push.rocks/smartradius';

const client = new RadiusClient({
  host: '192.168.1.1',
  secret: 'shared-secret',
});

await client.connect();

// Session start
await client.accountingStart('session-123', 'username');

// Interim update
await client.accountingUpdate('session-123', {
  username: 'username',
  sessionTime: 300,
  inputOctets: 1024000,
  outputOctets: 2048000,
});

// Session stop
await client.accountingStop('session-123', {
  username: 'username',
  sessionTime: 600,
  inputOctets: 2048000,
  outputOctets: 4096000,
  terminateCause: 1,  // User-Request
});

await client.disconnect();
```

### Custom Attributes

```typescript
const result = await client.authenticate({
  username: 'user',
  password: 'pass',
  nasPort: 1,
  calledStationId: 'AA-BB-CC-DD-EE-FF',
  callingStationId: '11-22-33-44-55-66',
  customAttributes: [
    { type: 'Service-Type', value: 2 },  // Framed
    { type: 26, value: Buffer.from('vendor-data') },  // VSA
  ],
});
```

## Client Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `host` | string | *required* | RADIUS server address |
| `authPort` | number | 1812 | Authentication port |
| `acctPort` | number | 1813 | Accounting port |
| `secret` | string | *required* | Shared secret |
| `timeout` | number | 5000 | Request timeout (ms) |
| `retries` | number | 3 | Number of retries |
| `retryDelay` | number | 1000 | Base delay between retries (ms) |
| `nasIpAddress` | string | '0.0.0.0' | NAS-IP-Address attribute |
| `nasIdentifier` | string | 'smartradius-client' | NAS-Identifier attribute |

## Response Properties

### IClientAuthResponse

| Property | Type | Description |
|----------|------|-------------|
| `code` | ERadiusCode | Response packet code |
| `accepted` | boolean | True if Access-Accept |
| `rejected` | boolean | True if Access-Reject |
| `challenged` | boolean | True if Access-Challenge |
| `replyMessage` | string | Reply-Message attribute |
| `sessionTimeout` | number | Session-Timeout in seconds |
| `framedIpAddress` | string | Assigned IP address |
| `attributes` | IParsedAttribute[] | All response attributes |

## Re-exports

This module re-exports all types from `ts_shared` for convenience.