RBAC-ready multi-session support with role-based permissions

[pennycoders]

Multi-Session Support with Role-Based Access Control

Implements concurrent WebRTC session management with granular permission control, enabling multiple users to connect simultaneously with different access levels.

Overview

JetKVM now supports up to 10 simultaneous connections per device with automatic session management and conflict resolution. The multi-session system uses role-based permissions to control access and ensures system availability through intelligent session promotion algorithms.

Key Features

• Multiple concurrent connections - Up to 10 simultaneous sessions per device
• Role-based permissions - Four distinct session modes (Primary, Observer, Queued, Pending)
• Automatic session promotion - Seamless handoff between primary sessions
• Grace period reconnection - 10-second window to recover from accidental disconnects
• Session approval workflow - Optional gating for new connections
• Transfer protection - 60-second blacklist prevents unwanted session takeovers
• Emergency promotion - Trust-based algorithm prevents deadlock situations
• Activity timeout - Configurable inactivity timeout for primary sessions (default: 5 minutes)

Session State Flow

flowchart TD
    A[New Connection] --> B{Primary<br/>Exists?}
    B -->|No| C[Assign PRIMARY]
    B -->|Yes| D{Approval<br/>Required?}
    D -->|No| E[Assign OBSERVER]
    D -->|Yes| F[Assign PENDING]

    E --> G{Want<br/>Control?}
    G -->|Yes| H[Request Control]
    H --> I[Become QUEUED]
    I --> J{Primary<br/>Approves?}
    J -->|Yes| K[Transfer to PRIMARY]
    J -->|No| E

    F --> L{Approved by<br/>Primary?}
    L -->|Yes| E
    L -->|No| M[Disconnect]

    C --> N[Has Full Control]
    K --> N

    style C fill:#90EE90
    style E fill:#87CEEB
    style I fill:#FFD700
    style F fill:#FFB6C6
    style N fill:#98FB98

Loading

Grace Period & Reconnection

Protects against accidental disconnects (network issues, browser refresh, etc.):

flowchart TD
    A[Connection Lost] --> B[Start Grace Period<br/>10 seconds]
    B --> C{Was Primary?}
    C -->|Yes| D[Reserve Primary Slot]
    C -->|No| E[Track in Grace Map]
    D --> F{Reconnect Within<br/>Grace Period?}
    E --> F
    F -->|Yes| G[Restore Session<br/>Same Mode]
    F -->|No - Timeout| H{Was Primary?}
    H -->|Yes| I[Promote Next Session]
    H -->|No| J[Remove from Grace Map]
    G --> K[Session Active]
    I --> K

    style D fill:#FFD700
    style G fill:#90EE90
    style I fill:#87CEEB

Loading

Grace Period Details:

• Configurable duration (1-300 seconds, default 10 seconds)
• Maximum 10 concurrent grace periods (DoS protection)
• Primary slot reserved during grace period
• Automatic cleanup on expiration

Emergency Promotion Algorithm

Ensures system always has a primary session when sessions exist:

flowchart TD
    A[Emergency Promotion Triggered] --> B{Approval<br/>Required?}

    B -->|No| C[Simple First-Eligible]
    C --> D{Queued Sessions<br/>Exist?}
    D -->|Yes| E[Promote First<br/>Queued Not Blacklisted]
    D -->|No| F{Observer Sessions<br/>Exist?}
    F -->|Yes| G[Promote First<br/>Observer Not Blacklisted]
    F -->|No| H{Pending Sessions<br/>Exist?}
    H -->|Yes| I[Promote First<br/>Pending Not Blacklisted]
    H -->|No| J[No Sessions Available]

    B -->|Yes| K[Trust-Based Scoring]
    K --> L[Calculate Trust Scores:<br/>Age + Previous Primary +<br/>Mode + Nickname]
    L --> M{Observers/Queued<br/>Available?}
    M -->|Yes| N[Score Observers/Queued]
    M -->|No| O[Score Pending]
    N --> P[Select Highest Score]
    O --> P
    P --> Q[Promote Winner]

    E --> R[New Primary Active]
    G --> R
    I --> R
    Q --> R

    style E fill:#90EE90
    style G fill:#87CEEB
    style I fill:#FFB6C6
    style L fill:#FFD700
    style P fill:#DDA0DD

Loading

Trust Scoring Factors:

• Session age (0-100 points, capped to prevent overflow)
• Previous primary status (+50 points)
• Current mode: Observer (+20), Queued (+10), Pending (0)
• Nickname presence (+15 if required, -30 if missing when required)

Emergency Promotion Triggers:

1. No primary exists (validation check every 10 seconds)
2. Primary session timeout (default: 5 minutes of inactivity)
3. Grace period expiration without reconnection

Rate Limiting (when approval required AND primary exists):

• Sliding window: Max 3 promotions per 60 seconds
• Cooldown: 10 seconds between emergency promotions
• Consecutive: Max 3 consecutive emergency promotions
• All limits bypassed when no primary exists (prevents deadlock)

Session Modes & Permissions

Primary (Full Control)

• View video feed
• Send keyboard/mouse input
• Control power (ATX/DC)
• Mount/unmount virtual media
• Manage all settings
• Approve/deny sessions
• Transfer control to others
• Access terminal/serial console
• Timeout: 5 minutes inactivity (configurable)

Observer (View-Only)

• View video feed
• See mounted media (read-only)
• Request primary control
• View session list
• Timeout: 30-60 seconds after RPC channel closes (configurable)

Queued (Waiting for Control)

• All Observer permissions
• Visible in primary's approval queue
• Can be approved/denied by primary

Pending (Awaiting Access)

• No video access
• No input capabilities
• Must be approved by primary to become Observer
• Auto-removed after 1 minute if not approved (DoS protection)

Technical Implementation

Architecture

• Permission System: Centralized RBAC in internal/session package (28 unique permissions)
• Session Management: Concurrent-safe SessionManager with atomic operations
• Emergency Promotion: Multi-layer rate limiting with trust-based selection
• Grace Period: Time-bounded reconnection map with automatic cleanup
• Transfer Blacklist: 60-second cooldown after manual transfers

Security & DoS Protection

• Broadcast throttling (100ms global, 50ms per-session)
• Defense-in-depth permission validation at RPC and method levels
• Pending session timeout (1 minute)
• Grace period limits (max 10 concurrent)
• Emergency promotion rate limiting (3 layers)
• Session count limits (configurable, default 10)
• Rejection attempt tracking (3 strikes, 60-second cooldown)

Performance Optimizations

• Pre-allocated event maps for hot-path operations
• Lock-free session iteration with snapshot pattern
• Efficient broadcast with throttling
• Atomic nickname updates
• Integer overflow protection in trust scoring

Session Settings

All settings configurable via UI or API:

Setting	Default	Range	Description
Require Approval	false	boolean	New sessions need primary approval
Require Nickname	false	boolean	Sessions must set nickname
Reconnect Grace	10s	1-300s	Grace period for reconnection
Primary Timeout	300s	0-3600s	Inactivity timeout (0=disabled)
Observer Timeout	30s	0-3600s	Cleanup timeout for closed observers
Private Keystrokes	false	boolean	Hide keyboard input from observers
Max Sessions	10	1-50	Maximum concurrent sessions
Max Rejection Attempts	3	1-10	Strikes before 60s cooldown

Session Identification

• Automatic nickname generation from User-Agent (e.g., "Chrome on macOS")
• Manual nickname customization
• Validation: 2-32 chars, alphanumeric + spaces + -_.@
• Uniqueness enforcement

Activity Tracking

Primary inactivity timer resets on:

• Keyboard input (HID RPC keyboard reports)
• Mouse input (HID RPC mouse movement, clicks, wheel)
• Any valid JSON-RPC method call

Explicitly excluded:

• Jiggler automated mouse movement (intentional - maintains keyboard auto-release only)
• WebSocket signaling messages
• WebRTC connection keep-alives

[SilkePilon]

Nice job with this one, will try it out myself. Any things i need to know about to set it up @pennycoders ?

[pennycoders]

Nice job with this one, will try it out myself. Any things i need to know about to set it up @pennycoders ?

Nope, everything should just be built and deployed how it normally is. Just the fact that I did not get a chance to test it in "cloud mode", since I don't have a cloud environment that I can test with. Will get around to setting one up, but not sure when. When the password auth is disabled it is a little flaky, but from what I was able to test it works pretty well. I actually think it would be great if you could put it through its paces