> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.orbitdev.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Orbit Control Architecture and Threat Model

> Orbit Control trust boundaries, data flow, threats, controls, and the capability/risk matrix that governs device-bound command execution.

Orbit Control is the security foundation and safe-MVP specification for device-bound command execution. This page covers the trust boundaries, data flow, primary threats and controls, the capability and risk matrix, platform limitations, and residual risks that require specialist review. Sensitive device execution is not production-enabled.

<Warning>
  Sensitive device execution is not production-enabled. This architecture is a security foundation and safe-MVP specification.
</Warning>

## Trust boundaries and data flow

The command lifecycle crosses three trust zones: the authenticated dashboard, the command gateway, and the paired device. Each zone enforces policy independently.

<Steps>
  <Step title="Dashboard proposes action">
    The authenticated dashboard proposes a typed action. Retrieved content is data, never policy.
  </Step>

  <Step title="Gateway validates and gates">
    The command gateway validates identity, current session, ownership, capability, risk, consent, and rate limits.
  </Step>

  <Step title="Preview and confirmation">
    Medium actions show a preview. High actions require confirmation plus AAL2 step-up. Critical actions add a second confirmation.
  </Step>

  <Step title="Gateway signs device-bound command">
    The gateway signs a device-bound command with a unique nonce and a lifetime of at most five minutes.
  </Step>

  <Step title="Device verifies independently">
    The paired device independently verifies signature, nonce, expiry, device ID, current local grant, and local approval.
  </Step>

  <Step title="Device executes least-privileged action">
    The device uses the least-privileged OS API, keeps sensitive access visible, and returns a bounded result.
  </Step>

  <Step title="Audit event is appended">
    The gateway appends an audit event. Models and ordinary clients cannot modify audit rows.
  </Step>
</Steps>

Cloud failure must fail closed. The local device retains Stop Control and Lockdown controls when offline.

## Primary threats and controls

| Threat | Required control |
| - | - |
| Cross-account IDOR | Owner-bound foreign keys, RLS on every exposed table, server revalidation |
| Pairing-code theft or brute force | SHA-256 digest only, single use, session binding, ten-minute maximum, attempt cap, rate limit |
| Command replay or forgery | Asymmetric device identity, gateway signature, nonce uniqueness, expiry, device-side verification |
| Prompt injection | Untrusted-content boundary, allowlisted action schema, no direct model execution |
| Permission escalation | Enumerated capabilities, no `full_control`, model cannot write grants |
| Confirmation bypass | Risk-derived server policy, AAL2 for high/critical, two confirmations for critical |
| Hidden surveillance | Persistent local indicator, OS consent, local prompt, automatic expiry, emergency stop |
| Audit tampering | Append-only client permissions, restricted RPC writers, retention controls |
| Compromised session | Short access lifetime, refresh rotation, session revocation, suspicious-login alerting |
| Path/URL/app injection | Typed parameters, canonical paths, allowlisted apps and schemes, symlink-safe device APIs |

## Capability and risk matrix

| Capability | Default | Risk | Additional gate |
| - | -: | -: | - |
| Device status, media, approved app launch | Off | Low | Explicit device grant |
| Calendar change, notification management, approved transfer | Off | Medium | Preview and confirmation |
| Screen, camera, microphone, location, approved terminal | Off | High | AAL2, explicit confirmation, OS prompt, visible indicator |
| Delete/reset, security/account change, lock/restart/wipe | Unsupported initially | Critical | AAL2, impact warning, second confirmation |

Terminal access never means a generic shell. A separately configured command policy must bind executable, arguments, working directory, duration, and output limits.

## Platform capability matrix

| Platform | Safe MVP | Important limitation |
| - | - | - |
| Windows/macOS/Linux | Status, notifications, approved apps, media; requested screen share | Native agent must be signed, sandboxed, visible, and least privileged |
| Android | User-approved notifications/media and foreground remote-assistance session | Background execution and accessibility are OS/policy constrained; no silent capture |
| iOS | Status, notifications, Shortcuts/deep links, user-initiated screen broadcast where permitted | No general remote control, silent camera/mic, arbitrary files, or background screen capture |
| Web | Dashboard, approvals, audit, WebRTC viewer | Browser cannot control arbitrary OS applications or files |
| Smart devices | Vendor-authorized APIs only | Each vendor scope and household consent model applies |

## Residual risks

The following risks require specialist review:

* Native-agent sandbox escapes
* OS accessibility abuse
* Signing-key compromise
* TURN/WebRTC metadata exposure
* Organization consent validity

## Monorepo target

The current repository remains operational while migration proceeds toward:

* `apps/web`
* `apps/desktop`
* `apps/android`
* `apps/ios`
* `services/gateway`
* `services/notifications`
* `packages/control-sdk`

Do not duplicate security policy between apps. The shared SDK defines schemas, while the gateway and native agent each enforce policy independently.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.