117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# 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
|