Digital Lock On

Appearance

ADR-006: Handover Flow Design ​

Status: Completed
Date: 2025-08-20
Affects: REQ-PROT-008: Worksite Protector Handover

Context ​

The team needed to design a secure handover process between protectors that prevents malicious use while maintaining safety. The key challenge was ensuring that only one protector has control of a worksite at any time, especially in scenarios where devices might go offline during the handover process.

Three main approaches were considered:

  1. WebRTC-based handover - Device-to-device communication with offline sync capabilities
  2. QR code-based handover - Server-mediated process requiring online connectivity
  3. 6-digit code based handover - Server-mediated process requiring online connectivity

Decision ​

We will implement a 6-digit code based handover with the following characteristics:

  1. Authentication: Incoming protectors are identified via signing in on their iPad
  2. Online-Only Requirement: Both devices must remain online throughout the entire handover process
  3. Two-Step Confirmation: Outgoing protector initiates handover and views a unique 6-digit site code (alphanumeric); the incoming protector accepts by initiating takeover and entering the 6-digit code correctly. Final handshake confirms the site has handed over
  4. Heartbeat System: Outgoing protector sends periodic heartbeats to maintain session validity
  5. Automatic Cancellation: Handover automatically cancels if outgoing protector goes offline after 10 min.

Consequences ​

Positive ​

  • Simpler Implementation: Same 6-digit code flow can be re-used for secure Emergency Takeover process (with additional controls in place, by RPO and System Administrator)
  • Better Security: Server-mediated process prevents device-to-device manipulation
  • Audit Trail: All handover actions are logged server-side
  • Faster Delivery: Focuses on core safety rather than complex technology
  • Robust Offline Handling: Clear failure states when connectivity is lost

Negative ​

  • Connectivity Dependency: Requires both devices to remain online
  • Additional Complexity: Heartbeat system adds backend complexity
  • User Experience: Slightly more steps than a direct device-to-device transfer
  • Edge Case Handling: Need to handle heartbeat timeouts and network issues
  • Physical Presence: Does not ensure that someone is physically present on-site; 6-digit code could be shared over radio and intercepted. Correct human process needs to be established.

Neutral ​

  • Future Enhancement: WebRTC could be added later as an enhancement
  • Fallback Options: RPO can assign themselves as a Site Protector; or System Administrator can facilitate an emergency handover/takeover.

Implementation Notes ​

6-digit code system ​

  • Unique 6-digit code is generated on the backend
  • Code is established on site protection and invalidated if handover is cancelled, the Protector changes, or site is deactivated
  • See Protector Handover - UI Specification for more details

Heartbeat System ​

  • Outgoing protector sends heartbeats every 5-10 seconds
  • Server automatically cancels handover if heartbeat is missed or handover session times out
  • Incoming protector's acceptance is confirmed only after next heartbeat from outgoing protector

Data Model ​

  • New Handover entity separate from existing site flags
  • Schema: { id, siteId, outgoingUserId, incomingUserId, startDate, endDate, status }
  • Status values: pending, completed, cancelled

API Design ​

  • GET, POST, PATCH endpoints for handover management
  • Heartbeat endpoint for session maintenance
  • Status polling for real-time updates

Alternatives Considered ​

WebRTC Approach ​

  • Pros: Device-to-device communication, offline sync capabilities
  • Cons: Complex implementation, browser compatibility issues, higher development effort
  • Rejection Reason: Over-engineering for the safety requirements, slower delivery

Simple QR Handover ​

  • Pros: Minimal implementation effort
  • Cons: No offline protection, potential for malicious use
  • Rejection Reason: Insufficient security for safety-critical operations

Encrypted QR Handover ​

  • Pros: Uses existing QR patterns
  • Cons: Requires connectivity; requires a different process and technology for emergency handovers
  • Rejection Reason: 6-digit code process serves both routine and emergency handovers.

Review Notes ​

This decision was made during the detailing session on 2025-08-20 with input from the development team. The approach prioritises safety and auditability over technological sophistication, which aligns with the critical nature of rail protection operations.

Internal use only