Jitsi Room Whitelist Service

🔐 Not a vibe-coded project

Written by hands, not AI

A lightweight Express-based API service that manages temporary Jitsi room access through a whitelist system. This service generates unique room IDs, manages their lifecycle, and provides an authentication endpoint that can be integrated with Jitsi Meet (e.g., via nginx auth_request).

Features

• Dynamic Room Creation: Generate simple (human-readable) or strong (cryptographically secure) room IDs
• Temporary Access: Rooms expire automatically after a configurable duration
• Authentication Endpoint: Integrate with reverse proxies (nginx, etc.) for access control
• Room Management: List active rooms and manually delete rooms
• Type-Safe: Built with TypeScript and Zod for runtime validation

Installation

npm install

Configuration

Copy the example environment file and configure:

cp .env.example .env

Environment Variables

• PORT - Server port (default: 3000)
• SERVICE__PUBLIC_URL - Public URL for your Jitsi instance (e.g., https://meet.example.com/)

Usage

Development

npm run start:dev

Production

npm run build
npm start

API Reference

Create Room

POST /api/rooms

Creates a new temporary room with optional custom or auto-generated ID.

Request Body:

{
  "room_id": "my-room", // Optional: custom room ID (min 3 chars)
  "generate_variant": "simple", // Optional: "simple" or "strong" (default: "simple")
  "generate_simple_sections": 2, // Optional: sections for simple generation (1-8)
  "generate_strong_sections": 2, // Optional: sections for strong generation (1-5)
  "generate_strong_symbols": 5, // Optional: symbols per section (3-8)
  "duration_hours": 24 // Optional: room lifetime in hours (default: 24)
}

Response:

{
  "success": true,
  "room_id": "1234-5678",
  "url": "https://meet.example.com/1234-5678",
  "expires_at": "2025-10-16T20:30:00.000Z"
}

Generation Examples:

• Simple: 1234-5678 (human-readable 4-digit sections)
• Strong: 8f4b9-985c6 (cryptographically secure hex strings)

List Active Rooms

GET /api/rooms

Returns all currently active rooms.

Response:

{
  "active_rooms": 2,
  "rooms": [
    {
      "room_id": "1234-5678",
      "created": "2025-10-15T20:30:00.000Z",
      "expires": "2025-10-16T20:30:00.000Z",
      "hits": 5
    }
  ]
}

Delete Room

DELETE /api/rooms/:room_id

Manually deletes a room before expiration.

Response:

{
  "success": true,
  "message": "Room deleted"
}

Authenticate Access

GET /auth/:room_id

Authentication endpoint for reverse proxy integration. Returns HTTP 200 if room exists, 403 if not.

Response:

• 200 OK - Room is valid and active
• 403 Forbidden - Room not found or expired

Health Check

GET /health

Service health and status endpoint.

Response:

{
  "status": "ok",
  "active_rooms": 2
}

Integration Example

Nginx Auth Request

Configure nginx to use this service for Jitsi room authentication:

location ~ ^/([a-zA-Z0-9-]+)$ {
    auth_request /auth;
    proxy_pass http://jitsi-backend;
}

location = /auth {
    internal;
    proxy_pass http://localhost:3000/auth/$1;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
}

Project Structure

src/
├── server.ts              # Main Express server and route handlers
├── config.ts              # Configuration management
├── utils.ts               # Room ID generation utilities
├── schemas/
│   ├── newRoomSchema.ts   # Request validation schema
│   └── shared.ts          # Shared Zod validators
└── ts/
    └── room.ts            # Room interface definition

Tech Stack

• Runtime: Node.js
• Framework: Express 5
• Language: TypeScript
• Validation: Zod
• Environment: dotenv

License

ISC