SC Savant Cyprus Official Distributor for Cyprus

Sentinel Documentation

Sentinel Pro Engineering Whitepaper v4.2

Full engineering and security whitepaper for Sentinel Pro and Sentinel Savant Rubi Bridge, adapted from the original markdown into structured web format.

Version 4.2 Date: 2026-03-31 Engineering Reference
Installation Guide Doorbell Workflow Back to Sentinel Pro

1. Executive Summary

Sentinel is a homeowner-first monitoring and control-governance platform for Savant systems. It is delivered as Sentinel Pro App (iPhone, iPad, Apple TV) and Sentinel Savant Rubi Bridge (Ruby runtime on the Savant host).

Sentinel is designed to provide high-value system visibility and controlled actions while preserving homeowner authority over integrator access. This v4.2 whitepaper defines the full concept, architecture, communication protocols, cryptography profile, security posture, and homeowner-centric privacy model.

2. Scope and Product Concept

Sentinel is intentionally more than a dashboard. It is an operational control plane with explicit trust governance.

Primary goals

  1. Give homeowners clear, continuous visibility into system health.
  2. Enable integrators to diagnose and support safely.
  3. Enforce owner-controlled authorization and revocation.
  4. Keep host overhead low for large deployments.
  5. Preserve clear technical boundaries between telemetry and privileged actions.

Out of scope

  • Unbounded remote shell exposure to all users.
  • Full raw host data exfiltration.
  • Cloud dependency for core local monitoring operation.

3. Architecture Overview

Sentinel uses a layered architecture:

  1. Bridge layer (host-local Ruby service in Savant Rubi environment).
  2. App layer (SwiftUI client across iOS/tvOS targets).
  3. Persistent local Sentinel store (users, policy, audit, generated manifests).
  4. Savant state and runtime sources (StateCenter via sclibridge, host runtime).

3.1 Data Plane

Savant StateCenter and runtime signals are harvested and normalized by the bridge, then delivered to clients via curated JSON APIs.

StateCenter/readstate -> harvest engine -> normalized cache -> app UI

3.2 Control Plane

Actions are gated through role policy, ACL checks, and action-specific safety logic before host mutation is attempted.

app action -> authentication -> authorization + ACL -> guarded execution -> audit

4. Bridge Design

Bridge runtime file: savant_network_sentinel_clean_rubi_bridge_v4_0_pro.rb | Runtime constant: 4.1-pro | Runtime model: WEBrick API service + harvest loop + local persistence.

4.1 Network Service Model

  • Bind host is configurable (bind_host), default 0.0.0.0.
  • Port is configurable (app_port), default 42042.
  • Bridge can run HTTP or HTTPS based on Blueprint/runtime config.

4.2 Harvesting and Scalability

  • Controlled candidate discovery and manifest strategy.
  • Batched polling with configurable cap (harvest_max_states).
  • Separation of frequently changing telemetry and stable identity metadata.

4.3 Safety-Critical Command Handling

  • Critical commands require explicit action payload and role authorization.
  • Terminal sessions are time-bounded and auditable.
  • Doorbell audio actions validate compatibility before reference replacement.

4.4 Persistent State

  • Users and password hashes.
  • Role and ACL permissions.
  • Policy flags for pairing and authorization state.
  • Audit log (sentinel_audit.jsonl, retention window 90 days).
  • Generated bridge catalog and manifests.

5. App Design

Sentinel Pro app is the user-facing control and monitoring surface:

  • iPhone: compact operational controls and incident response.
  • iPad: denser multi-panel service visibility.
  • Apple TV: persistent home status board for shared visibility.

5.1 UX Governance Features

  • First-login password rotation flow.
  • Role and monitoring acknowledgment gates.
  • Integrator authorization by homeowner admin.
  • Explicit owner controls for temporary disable and permanent integrator revoke.

5.2 Operational Surfaces

  • System dashboard and service rollups.
  • StateCenter-driven status cards.
  • Admin user and permission management.
  • Audit activity views.
  • Tools (terminal and controlled host actions).
  • Doorbell audio management workflow.

6. Communication Protocols

6.1 Transport

  • Local network or VPN path to bridge endpoint.
  • HTTP/1.1 JSON API over HTTP or HTTPS (WEBrick server).
  • Default transport recommendation: HTTPS enabled.

6.2 API Style

  • REST-like endpoint model.
  • UTF-8 JSON request and response.
  • Status-code based error handling with structured payloads.
  • Authorization: Bearer <token> for authenticated endpoints.

6.3 Endpoint Families

  • Health and metadata: /, /health
  • Authentication and identity: /api/v1/auth/login, /api/v1/auth/me, /api/v1/auth/change-password
  • Pairing and acknowledgment: /api/v1/acknowledgements/monitoring, /api/v1/acknowledgements/role, /api/v1/pairing/authorize-integrator
  • Site data: /api/v1/site/config, /api/v1/site/status, /api/v1/site/discovery, /api/v1/site/host-runtime
  • Admin and audit: /api/v1/admin/users, /api/v1/admin/monitoring, /api/v1/audit, /api/v1/admin/audit
  • Tools: terminal endpoints, reboot endpoint, doorbell endpoints.

6.4 Session Protocol

  • Random bearer token issued on successful login.
  • Session carries role, expiry, and required-next-step flags.
  • Authorization is re-evaluated against policy and ACL state.
  • Expired sessions are purged server-side.

7. Cryptography Profile

7.1 TLS and Bridge Identity

  • Host-local X.509 certificate and key generated or loaded when HTTPS is enabled.
  • Key type: RSA 2048-bit.
  • Digest: SHA-256.
  • Fingerprint computed as SHA-256 of DER certificate bytes and exposed by API.

7.2 App Trust Behavior

  • App supports expected fingerprint comparison per home configuration.
  • Fingerprint mismatch is rejected as bridge identity change when configured.
  • If no fingerprint is configured, TLS chain acceptance is less strict.

Operational implication: for production security, each home should store and enforce TLS fingerprint pinning in app configuration.

7.3 Password Storage

  • Algorithm: PBKDF2-HMAC-SHA256.
  • New-password iteration count: 210,000.
  • Legacy compatibility iteration count: 20,000.
  • Per-user random salt: SecureRandom.hex(16).
  • Hash output stored instead of plaintext.

7.4 Session Secrets

  • Session tokens generated with SecureRandom.hex(24).
  • Tokens are held in bridge memory and not intended for long-term storage.

8. Security Architecture

8.1 Role Model

Primary roles: integrator, home_admin, home_user.

  • Singleton integrator and singleton home admin constraints.
  • Homeowner authority for integrator authorization.
  • Homeowner controls for temporary disable and permanent revoke.

8.2 ACL Model

Permissions are normalized across services, devices, states, and actions for least-privilege filtering of both data visibility and action eligibility.

8.3 Governance Gates

  • Mandatory password change gates.
  • Monitoring and role acknowledgment gates.
  • Pairing completion requirements.
  • Action-level checks before host mutation.

8.4 Audit and Accountability

  • Security and admin events logged as JSONL entries.
  • Retention policy: 90 days with pruning.
  • Audit surfaces role-filtered in API and app UI.

9. Homeowner-Centric Privacy Design

Sentinel privacy design is based on five principles: owner authority, explicit consent and acknowledgment, data minimization, locality by default, transparent accountability.

9.1 Data Minimization

  • Curated telemetry instead of unrestricted host internals.
  • State namespace access filtered by ACL and role.
  • Sensitive text masked where practical.

9.2 Locality and Data Residency

  • Core monitoring path remains local over LAN or VPN.
  • User store and audit logs are host-local files.
  • No mandatory cloud dependency for core telemetry path.

9.3 Consent and Revocability

  • Homeowner acknowledgment and authorization are first-class gates.
  • Integrator access can be temporarily disabled or permanently revoked.
  • Revocation is durable in policy and reflected in session behavior.

9.4 What Is Not Claimed

  • Baseline does not claim fully encrypted-at-rest stores for all Sentinel files.
  • TLS pinning availability depends on operator configuration in app.

10. Threat Model and Residual Risk

10.1 Addressed Threats

  • Credential disclosure in transit mitigated by HTTPS.
  • Weak password persistence mitigated by PBKDF2 + policy + forced rotation.
  • Unauthorized endpoint access mitigated by bearer auth + role + ACL checks.
  • Silent support access mitigated by homeowner authorization and audit trails.

10.2 Residual Risks

  • Self-signed certificate trust must be operationally managed.
  • Unpinned TLS mode weakens identity binding.
  • Compromised trusted client can misuse valid tokens until expiry.
  • Host filesystem permissions remain important for local file confidentiality.

11. Security Hardening Roadmap

  1. Enforce HTTPS and fingerprint pinning by default for new homes.
  2. Add explicit in-app fingerprint onboarding and rotation workflow.
  3. Shorten privileged session lifetime and add finer re-auth controls.
  4. Add stronger mutation replay protections for critical commands.
  5. Expand endpoint-level rate limits and lockout telemetry.
  6. Add optional encrypted-at-rest storage for sensitive Sentinel files.

12. Verification and Testing Framework

  • Unit tests for auth, ACL, and password policy behavior.
  • API contract validation for success and error schemas.
  • TLS and fingerprint mismatch simulation tests.
  • Harvest performance checks on high-state-count homes.
  • Audit log generation and retention-prune verification.
  • Permission boundary tests for integrator, home_admin, and home_user.

13. Conclusion

Sentinel is engineered as a secure, homeowner-governed operational platform for Savant estates. Its design combines practical host-compatible bridge architecture, role- and ACL-aware app experiences, explicit governance and revocation controls, modern cryptographic primitives for credentials and transport, and privacy-centric data minimization with local-first operation.

This framework allows Sentinel to scale feature depth while preserving trust, safety, and owner control.

Next: Installation & Capabilities Doorbell Workflow Back to Sentinel Pro