smartradius/readme.hints.md

# Project Hints - smartradius

## Project Status
- **Current State**: Fully implemented RADIUS server and client
- **Purpose**: RADIUS protocol implementation for network AAA (Authentication, Authorization, Accounting)
- **Version**: 1.0.1
- **RFC Compliance**: RFC 2865 (Authentication) and RFC 2866 (Accounting)

## Architecture

### Module Structure
```
ts_server/         (order: 1) - RADIUS Server implementation
ts_client/         (order: 2) - RADIUS Client implementation
ts/                (order: 3) - Main exports (re-exports server + client)
```

### Key Classes

#### Server Module (ts_server/)
- `RadiusServer` - Main server class with UDP listeners for auth (1812) and accounting (1813)
- `RadiusPacket` - Packet encoding/decoding per RFC 2865 Section 3
- `RadiusAttributes` - Attribute dictionary with all standard RFC 2865/2866 attributes
- `RadiusAuthenticator` - Cryptographic operations (PAP, CHAP, MD5, HMAC-MD5)
- `RadiusSecrets` - Per-client shared secret management

#### Client Module (ts_client/)
- `RadiusClient` - Client with PAP/CHAP auth and accounting, timeout/retry support

## Implemented Features

### Authentication (RFC 2865)
- PAP (Password Authentication Protocol) with MD5-based encryption
- CHAP (Challenge-Handshake Authentication Protocol)
- Access-Request/Accept/Reject/Challenge packet handling
- Message-Authenticator (HMAC-MD5) for EAP support
- All standard attributes (1-63) plus EAP support (79, 80)

### Accounting (RFC 2866)
- Accounting-Request/Response packets
- Status types: Start, Stop, Interim-Update, Accounting-On/Off
- Full session tracking attributes
- Termination cause codes

### Protocol Features
- Duplicate request detection and response caching
- Response authenticator verification
- Configurable timeout and retry with exponential backoff
- Per-client shared secret management
- Vendor-Specific Attributes (VSA) support

## Dependencies
```json
{
  "@push.rocks/smartdelay": "^3.0.5",
  "@push.rocks/smartpromise": "^4.2.3"
}
```

Node.js built-ins: `node:dgram` (UDP), `node:crypto` (MD5/HMAC)

## Build System
- Uses `@git.zone/tsbuild` v4.x with tsfolders mode
- Build command: `pnpm build` (compiles ts_server → ts_client → ts)
- Test command: `pnpm test`

## Test Coverage
- 92 tests across 9 test files
- Server tests: packet, attributes, authenticator, PAP, CHAP, accounting
- Client tests: client functionality, timeout/retry, integration

## Usage Examples

### Server
```typescript
import { RadiusServer, ERadiusCode } from '@push.rocks/smartradius';

const server = new RadiusServer({
  authPort: 1812,
  acctPort: 1813,
  defaultSecret: 'shared-secret',
  authenticationHandler: async (request) => {
    if (request.username === 'user' && request.password === 'pass') {
      return { code: ERadiusCode.AccessAccept };
    }
    return { code: ERadiusCode.AccessReject };
  },
});
await server.start();
```

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

const client = new RadiusClient({
  host: '127.0.0.1',
  secret: 'shared-secret',
});
await client.connect();
const response = await client.authenticatePap('user', 'pass');
console.log(response.accepted);
```

## RFC Specifications
Downloaded to `./spec/`:
- `rfc2865.txt` - RADIUS Authentication
- `rfc2866.txt` - RADIUS Accounting

## Code Quality Notes
- All Node.js built-in imports use `node:` prefix (ESM/Deno/Bun compatible)
- Dead `smartpromise`/`smartdelay` imports removed from `ts_client/plugins.ts` (packages kept in package.json)
- Rust migration assessed as not cost-effective: crypto ops already delegate to OpenSSL C, RADIUS packets are small (max 4096 bytes), IPC overhead would negate any gains

## Last Updated
2026-02-11 - Fixed bare node: imports, removed dead imports, assessed Rust migration