Security and Permissions

Security and Permissions (RBAC)

PCLink implements a robust Role-Based Access Control (RBAC) system that ensures connected devices only access the features they are authorized for.

Authentication Overview

All communication with the PCLink server is encrypted via HTTPS. Authentication is split into two layers:

1. Web Admin Session: Protected by a user-defined password. Grants full access to management endpoints (/ui/*) and bypasses granular device permission checks.
2. Device API Tokens: Unique UUID tokens assigned to each mobile device upon pairing approval. These are passed via the X-API-Key header or a secure cookie.

Permission Enforcement

Every request to a resource-sensitive endpoint is intercepted by the service_enforcement_middleware. This middleware performs a three-step validation:

1. Global Service Status: It checks if the target service is enabled globally in the Server Settings. If a service is disabled globally, all requests to it are blocked, regardless of device permissions.
2. Identity Verification: It identifies the requester as either a Web Admin (via session cookie) or a paired device (via API token).
3. Capability Check: For paired devices, it verifies that the device's assigned permission set contains the required node for the requested endpoint.

Permission Nodes

The following nodes define granular access to server features:

Node	Title	Description
files_browse	File Browser	Browse system files, view thumbnails, and list directories
files_download	File Download	Download files from the host to the device
files_upload	File Upload	Upload files from the device to the host
files_delete	File Deletion	Delete files and folders on the host
processes	Processes	View and manage running system processes
power	Power Control	Shutdown, restart, or lock the host system
wol	Wake-on-LAN	Trigger Wake-on-LAN packets for network devices
info	System Status	Monitor battery, hardware, and system stats
mouse	Remote Mouse	Control system cursor and mouse clicks
keyboard	Remote Type	Send keyboard inputs and shortcuts
media	Media Control	Control playback and view media info
macros	Macros	Create, edit, and execute automated task chains
terminal	Terminal Access	High Risk: Full interactive shell access
desktop_streaming	Desktop Stream	View real-time desktop preview via FerrumCast
extensions	Extensions	Manage and run server-side extensions
apps	Applications	View and launch installed desktop apps
clipboard	Clipboard Sync	Read and write the system clipboard
screenshot	Screen Capture	Capture snapshots of the host display
command	Remote Command	Execute specific utility commands on the host
utils	Utilities	Access general system utility endpoints

Role Templates

To simplify management, the Web UI provides predefined templates for common use cases:

• Admin: Grants all available permissions.
• Viewer: files_browse, info, apps (Safe for basic monitoring).
• Media: media, volume, info, apps (Optimized for remote playback).
• Remote: mouse, keyboard, screenshot, info, volume (Desktop control).
• None: Revokes all access without deleting the device.

Device Revocation & Banning

• Revoke: Deletes the device's API token. The device must re-pair to connect again.
• Ban (Hardware ID): Permanently blacklists the device's unique hardware identifier. Even if the device attempts to re-pair, the server will reject the request at the network layer.

Global Kill-Switches

In the Access Control tab of the Web UI, the administrator can disable specific services globally. This overrides all device permissions, providing a "kill-switch" for features like Terminal or File Deletion across the entire fleet.