EntryPoint Security Architecture

Technical overview of application and relay command security controls.

Last updated: February 24, 2026

Scope and Enforcement

This document defines security controls used for sensitive mobile command execution in EntryPoint.

Current hard-enforced endpoint: POST /api/user/entry-point-on.

Version Gating

  • App version >= 1.1.3: hard enforcement of App Integrity and relay signature verification.
  • App version < 1.1.3: soft mode (logging and metrics, without blocking requests).
  • Version source: device record (device-register / appVersion field).

App Integrity Signature

Clients send integrity headers with key id, device binding, timestamps and DER-encoded ES256 signature.

Backend rebuilds canonical string exactly and verifies signature against configured public key by kid.

  • Canonical string: v1|METHOD|path-with-query|deviceId|bodySha256Hex|nonce|issuedAt|expiresAt
  • METHOD must be uppercase.
  • Path must be relative from /api.
  • Body hash must match SHA-256 of canonicalized request body.
  • TTL max 30s with clock-drift validation.

Relay Command Signature (entry-point-on)

Sensitive relay actions require payload signature validation for enforced app versions.

Boolean canonical values are serialized as strict strings "true" and "false".

  • Canonical string: v1|deviceId|status|stayOpen|delayTime|resetWifiConnection|resetLogs|checkWifiConnection|updateFirmware|opId|nonce|issuedAt|expiresAt
  • Signature format: ES256 (ECDSA P-256 + SHA-256), DER Base64.
  • Each retry must generate a fresh opId and nonce.

Anti-Replay Protection

  • App Integrity replay key: kid + nonce.
  • Relay replay key: kid + deviceId + opId + nonce.
  • Replay entries are stored in short TTL cache to prevent command re-use.

Error Signaling

Security checks return explicit machine-readable error codes to support safe client fallback and diagnostics.

  • App Integrity: APP_INTEGRITY_REQUIRED, APP_INTEGRITY_INVALID_SIG, APP_INTEGRITY_EXPIRED, APP_INTEGRITY_REPLAY and detailed mismatch codes.
  • Relay signature: RELAY_SIG_REQUIRED, RELAY_SIG_INVALID, RELAY_SIG_EXPIRED, RELAY_SIG_REPLAY.
  • Legacy relay ingest policy: SIGNATURE_REQUIRED for firmware >= 1.1.6.

Compatibility and Operational Notes

  • Older mobile clients remain supported through soft mode until migration is complete.
  • Legacy device flow remains available for firmware versions below 1.1.6.
  • Public keys are rotated through environment configuration without API contract changes.