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

{
  "@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

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

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