Skip to main content

Device Provisioning

Overview​

Device provisioning covers the full lifecycle from initial registration through certificate issuance, tenant assignment, and ongoing status monitoring. Two services handle certificates: DeviceCertificatesService (file-based CA) and CertificateManagementService (database-stored).

Registration Flow​

1. Auto-Register (Android TV devices)​

Devices call POST /devices/auto-register with their hardware identifiers. The AutoRegisterDto validates the payload, and the device is created under the authenticated user's tenant (via Prisma middleware).

2. Manual Registration​

Admins create devices via POST /devices with a CreateDeviceDto. The device gets an initial offline status and null lastSeen timestamp.

3. Device Connection​

Devices call POST /devices/connect with a ConnectDeviceDto. This updates lastSeen and sets status to online.

Certificate Management​

Issuance (issueCertificate)​

  1. RSA 2048-bit key pair generated via crypto.generateKeyPairSync
  2. Self-signed certificate built with device-specific subject (CN=Device-{id}, O=BTManagement, C=IL)
  3. Private key stored at certificates/devices/private/{id}-key.pem (mode 0o600)
  4. Public cert stored at certificates/devices/public/{id}-cert.pem
  5. Certificate record saved to DeviceCertificate model (global, not tenant-scoped)
  6. Event certificate.issued emitted

Configuration​

ConstantValueDescription
DEFAULT_CERT_VALIDITY_DAYS365Certificate lifetime
RENEWAL_WARNING_DAYS30Days before expiry to warn
AUTO_RENEWAL_DAYS7Days before expiry to auto-renew
DEFAULT_KEY_SIZE2048RSA modulus length

Certificate Lifecycle​

pending → active → (renewal warning at 30d) → (auto-renew at 7d) → expired
                                                                   → revoked
  • Monitoring: startMonitoring() runs on module init, checking expiry dates periodically
  • Renewal: Auto-renewal triggers when a certificate is within AUTO_RENEWAL_DAYS of expiry
  • Revocation: Certificates can be revoked with a reason; revokedAt and revocationReason are recorded
  • Validation: validateCertificate() checks expiry, revocation status, and fingerprint match

CA Infrastructure​

On first init (initializeCA), the service generates a self-signed CA key pair stored at:

  • certificates/ca-key.pem — CA private key
  • certificates/ca-cert.pem — CA certificate

All device certificates are signed by this CA.

Device Status Management​

Status Flags​

StatusMeaning
onlineDevice has reported within the last 5 minutes
offlineDevice has not reported within the last 5 minutes

Status Detection​

The DeviceStatusTask runs every minute (@Cron(CronExpression.EVERY_MINUTE)):

  1. Queries devices where status = 'online' AND lastSeen < (now - 5min)
  2. Batch-updates matching devices to offline
  3. Emits device.status_changed event per device for downstream processing (alerts, notifications, dashboard updates)

The 5-minute threshold is defined as RECENT_THRESHOLD_MS = 5 * 60 * 1000 in DevicesService.

Stats Overview​

getStatsOverview() returns a real-time summary:

  • total / active / offline device counts
  • alerts in last 24h — derived from DeviceMetrics (CPU > 90%, RAM > 85%)
  • recent alerts list with severity levels

Multi-Tenancy Notes​

Important
  • Device is a tenant-scoped model — all queries are auto-filtered by userId via Prisma middleware
  • DeviceCertificate is a global model — not tenant-filtered. Certificate operations must validate device ownership explicitly
  • Never add manual userId filters to device queries
  • DeviceConfigurationsModule — per-device display settings
  • DeviceMetricsModule — CPU, RAM, storage telemetry
  • DeviceMonitoringsModule — monitoring rules and thresholds
  • DeviceSettingsModule — user-facing device preferences
  • RemoteControlModule — remote command execution
  • SoftwareUpdatesModule — OTA update distribution