Docpilot System Lock - Tray Application

Overview

This application runs as a persistent user-mode lock agent that:

• Runs in the system tray (no main window)
• Polls a lock file every second
• Shows a full-screen lock UI when the session is locked
• Starts automatically on user login
• Never requires administrator privileges

---

Architecture

Components

1. LockFileMonitor.cs

   • Polls %TEMP%\sessionLock.json every 1000ms
   • Determines lock state based on file content
   • Raises events when lock state changes
   • Defaults to LOCKED on any error

2. LockScreenForm.cs

   • Full-screen, borderless, always-on-top form
   • Covers all monitors
   • Prevents minimize, close, and Alt+Tab
   • Shows lock message and branding

3. TrayApplicationContext.cs

   • Main application context running in system tray
   • Manages lock screen visibility based on monitor events
   • Provides tray menu with status and exit option

4. StartupManager.cs

   • Manages auto-startup via Windows Registry
   • Provides instructions for Scheduled Task alternative
   • Best-effort creation of startup entry

5. Program.cs

   • Entry point that initializes tray application
   • Single-instance enforcement (mutex)
   • Global exception handling
   • Logging to console and temp file

---

Lock File Contract

Location: %TEMP%\sessionLock.json

Format:

{
  "Email": "student@example.com",
  "SessionStarted": "2026-01-26T10:30:00.000Z",
  "Until": "2026-01-25T14:30:00.000Z"
}

Lock State Logic:

• File doesn't exist → LOCKED
• Parsing fails → LOCKED
• Until is null/empty → LOCKED
• Until <= DateTime.UtcNow → LOCKED
• Until > DateTime.UtcNow → UNLOCKED

---

Behavior

On Application Start

1. Checks for existing instance (only one allowed)
2. Initializes system tray icon
3. Starts lock file monitor
4. Checks/creates startup persistence entry
5. Shows lock screen if currently locked

When LOCKED

• Full-screen lock form is shown
• Covers all monitors
• Cannot be minimized or closed
• Always stays on top
• Regains focus if user tries to switch away

When UNLOCKED

• Lock form is hidden
• Application continues running in tray
• Shows "UNLOCKED" status in tray menu

---

Installation & Setup

Automatic Startup (Registry Method)

The application automatically attempts to create a registry entry on first run:

Registry Location: HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

Key: DocpilotSystemLock

Value: "C:\path\to\DocpilotSystemLock.exe"

This method works without admin rights and is automatically attempted.

---

Manual Startup (Scheduled Task Method)

If the registry method fails, you can manually create a Scheduled Task:

Method 1: Task Scheduler GUI

1. Press Win+R, type: taskschd.msc, press Enter

2. Click "Create Task..." (not "Create Basic Task")

3. General tab:

   • Name: DocpilotSystemLock
   • Description: Docpilot System Lock Agent
   • ✓ Run whether user is logged on or not
   • Configure for: Windows 10/11

4. Triggers tab:

   • Click New...
   • Begin the task: At log on
   • Specific user: [Your Username]
   • ✓ Enabled

5. Actions tab:

   • Click New...
   • Action: Start a program
   • Program/script: C:\path\to\DocpilotSystemLock.exe
   • Start in: C:\path\to\ (directory containing the exe)

6. Conditions tab:

   • ✗ Uncheck "Start the task only if the computer is on AC power"

7. Settings tab:

   • ✓ Allow task to be run on demand
   • ✓ Run task as soon as possible after a scheduled start is missed
   • If the task fails, restart every: 1 minute
   • Attempt to restart up to: 3 times

8. Click OK

Method 2: PowerShell (Run as Administrator)

$exePath = "C:\path\to\DocpilotSystemLock.exe"
$action = New-ScheduledTaskAction -Execute $exePath
$trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)
$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Highest

Register-ScheduledTask -TaskName "DocpilotSystemLock" -Action $action -Trigger $trigger -Settings $settings -Principal $principal -Force

Method 3: schtasks.exe (Command Prompt as Administrator)

schtasks /create /tn "DocpilotSystemLock" /tr "\"C:\path\to\DocpilotSystemLock.exe\"" /sc onlogon /rl highest /f

Verify the Task

schtasks /query /tn "DocpilotSystemLock"

Delete the Task (if needed)

schtasks /delete /tn "DocpilotSystemLock" /f

---

Building the Application

Debug Build

dotnet build

Release Build

dotnet build -c Release

Self-Contained Release (No .NET Runtime Required)

dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true

Output will be in: bin\Release\net10.0-windows\win-x64\publish\

---

Usage

Running the Application

• Double-click DocpilotSystemLock.exe
• Application will start in system tray (no window)
• Look for the lock icon in the system tray

System Tray Menu

• Status: Shows current lock state (🔒 LOCKED / ✅ UNLOCKED)
• Exit (Debug only): Exits the application with confirmation

Logs

Logs are written to:

• Console output (if running from terminal)
• Debug output (visible in debugger)
• %TEMP%\DocpilotSystemLock.log

---

Testing

Test Lock State

1. Create a lock file with future date:

@"
{
  "Email": "test@example.com",
  "SessionStarted": "2026-01-27T10:00:00.000Z",
  "Until": "2026-01-27T23:59:59.999Z"
}
"@ | Out-File -FilePath "$env:TEMP\sessionLock.json" -Encoding UTF8

2. Delete or rename the lock file to test locked state:

Remove-Item "$env:TEMP\sessionLock.json"

3. Create a lock file with past date (should lock immediately):

@"
{
  "Email": "test@example.com",
  "SessionStarted": "2026-01-27T10:00:00.000Z",
  "Until": "2026-01-27T10:00:01.000Z"
}
"@ | Out-File -FilePath "$env:TEMP\sessionLock.json" -Encoding UTF8

---

Security Considerations

What This App Does

• ✓ Monitors a lock file in user's temp directory
• ✓ Shows full-screen lock UI when required
• ✓ Auto-starts on user login
• ✓ Runs in user context (no elevation)

What This App Does NOT Do

• ✗ Does NOT run as a Windows Service
• ✗ Does NOT require administrator privileges
• ✗ Does NOT use session APIs or SYSTEM privileges
• ✗ Does NOT prevent Task Manager (by design, for safety)
• ✗ Does NOT prevent safe mode boot
• ✗ Does NOT prevent uninstallation

Limitations

• A determined user can kill the process via Task Manager
• A determined user can delete the startup entry
• A determined user can boot into safe mode
• This is intended as a soft lock for honest users, not a security enforcement tool

---

Troubleshooting

Application doesn't start automatically

1. Check if startup entry exists:
   • Open Registry Editor (regedit)
   • Navigate to: HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run
   • Look for DocpilotSystemLock entry
2. If not present, create a Scheduled Task (see above)
3. Check logs in %TEMP%\DocpilotSystemLock.log

Lock screen doesn't appear

1. Check if lock file exists: %TEMP%\sessionLock.json
2. Check if Until date is in the past
3. Check application logs
4. Try restarting the application

Application appears frozen

• The application has no main window by design
• Check system tray for the icon
• Check Task Manager for DocpilotSystemLock.exe process
• Check logs for errors

Can't exit the application

• In Debug builds, right-click tray icon → Exit
• In Release builds without Debug flag, use Task Manager
• This is intentional for deployment

---

Deployment

Recommended Deployment Steps

1. Build release version with self-contained option
2. Copy executable to target machine
3. Run the executable once to create startup entry
4. Verify startup entry was created
5. Test lock/unlock functionality
6. Reboot and verify auto-start

Removal

1. Exit the application (Debug build) or kill process
2. Delete startup registry entry or scheduled task
3. Delete the executable
4. Delete lock file: %TEMP%\sessionLock.json

---

Future Enhancements (Not Implemented)

• Custom icon support
• Configurable poll interval
• Multiple monitor improvements
• Localization support
• Windows Service version (if required)
• Telemetry and error reporting
• Configuration file support

---

License & Support

© 2026 Docpilot. All rights reserved.

For support, contact: support@docpilot.in