feat(smartradius): Implement full RADIUS server and client with RFC 2865/2866 compliance, including packet handling, authenticators, attributes, secrets manager, client APIs, and comprehensive tests and documentation

2026-02-01 17:40:36 +00:00
parent 5a6a3cf66e
commit be9f49fff9
45 changed files with 11694 additions and 70 deletions
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -0,0 +1,111 @@
+# 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: `dgram` (UDP), `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
+
+## Last Updated
+2026-02-01 - Full implementation complete with RFC 2865/2866 compliance