Security Boundaries & Pairing
Relevant source files
The following files were used as context for generating this wiki page:
The J.A.R.V.I.S. system architecture is founded on strict security boundaries that isolate machine authority from the user interface. By treating the local environment as a network location rather than an implicit authentication policy, the system ensures that sensitive capabilities like filesystem access and action execution are protected behind a deliberate capability bridge.
Security is managed through a three-party authoritative model: Electron owns the machine and native lifecycle, the Agent Backend owns the sessions and model workflows, and the Renderer owns the presentation. This separation is enforced via context isolation, restrictive Content Security Policies (CSP), and a pairing seam that requires explicit token exchange for personalized or sensitive operations.
Sources: instructions/design-backend-prompt.txt:12-25, instructions/AGENTS.md:15-25
Architectural Boundaries
The project is divided into distinct product boundaries to minimize the attack surface and prevent unauthorized access to local resources.
Component Isolation
| Component | Authority Scope | Security Constraint |
|---|---|---|
| apps/jarvis | Public landing page / Account dashboard | Static export; no local process dependencies. |
| backend (Local Service) | Chat streams, STT/TTS, Minimised status | Loopback-only; no shell or browser exposure. |
| apps/jarvis-desktop | Native lifecycle, IPC handlers, HUD Renderer | Sandboxed renderer; restrictive CSP; no Node integration. |
| packages/shared | API contracts, Design tokens, State validation | Runtime-validated types using Zod-free validators. |
Sources: instructions/design-backend-prompt.txt:12-25, instructions/design-backend-prompt.txt:43-46
Authority Model
The system dictates that state must reside with its specific authority:
- Electron (Main Process): Authoritative for machine facts, filesystem paths, and native windows.
- Backend: Authoritative for data shared across Jarvis surfaces (memory, chat history).
- Renderer: Authoritative only for immediate window presentation and ephemeral UI state.
Sources: instructions/AGENTS.md:27-35
Security Principles
- Local is not Auth: Loopback addresses do not grant implicit trust. Non-allowlisted browser origins are rejected.
- Pair Before Personalize: Read-only previews are unauthenticated, but personal memory or action routes require a revocable token.
- Sandboxed Renderer: Electron uses context isolation and a narrow preload bridge (
getPairingCode,onLiveEvent). - No Ambient Execution: Actions require human-in-the-loop approval and are limited by bounded capability scopes (e.g.,
scratchpad.write). - Environment Isolation: Sensitive keys like
XAI_API_KEYare injected into child processes without being written to disk.
Sources: instructions/design-backend-prompt.txt:94-105, instructions/design-backend-prompt.txt:68-70
Pairing Workflow
The pairing process establishes a secure session between a trusted client and the local service. It utilizes a 6-digit One-Time Password (OTP) generator and a token exchange mechanism.
The Pairing Sequence
The following sequence diagram illustrates the flow from code generation to token exchange:
The pairing generator is implemented as an in-memory service at POST /v1/pairing/code, and the exchanger resides at POST /v1/pairing/exchange.
Sources: instructions/design-backend-prompt.txt:40-44, backend/src/handler.ts:476-492
Pairing API Endpoints
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/v1/pairing/code | POST | { clientName: string } | Generates a short-lived 6-digit OTP. |
/v1/pairing/exchange | POST | { code: string, clientName: string } | Exchanges OTP for a scoped, revocable token. |
Sources: backend/src/handler.ts:476-492, packages/shared/tests/contracts.test.ts:98-103
Action Engine & Human-in-the-Loop
A critical security boundary is the "Human-in-the-Loop" architecture. No high-authority action (like executing a shell command or deleting memory) is performed without an explicit proposed -> approved lifecycle.
The JarvisActionEngine interface enforces this by requiring JarvisActionProposeRequest and JarvisActionDecideRequest structures.
Sources: instructions/design-backend-prompt.txt:72-78, backend/tests/action-engine.test.ts:4-15
Network Security
The backend service implements restrictive CORS and Origin validation to prevent Cross-Site Request Forgery (CSRF) and unauthorized access from browsers.
Origin Allowlisting
The createJarvisRequestHandler function checks the Origin header against a normalizeAllowedOrigins list. If the origin is not allowlisted, the service returns a 403 origin_forbidden error. Notably, /v1/chat is restricted exclusively to the private desktop shell.
Sources: backend/src/handler.ts:446-465
Content Security Policy (CSP)
The renderer interface is restricted by a strict CSP defined in the HTML header:
<meta http-equiv="Content-Security-Policy"
content="default-src 'self';
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' data:;
connect-src 'self' http://127.0.0.1:* ws://127.0.0.1:* https://api.open-meteo.com;
object-src 'none';
frame-src 'self' http://127.0.0.1:8794;
base-uri 'none';
form-action 'none'" />
Sources: src/index.html:8-13
Summary
Security in Jarvis-Glas is not a single layer but a multi-stage defense consisting of process isolation, strictly scoped authority, and a human-gated pairing and action engine. By requiring tokens stored in the OS credential vault and enforcing Zod-free runtime validation on all inter-process communication, the system ensures that the "Master" retains full control over the local environment.
Sources: instructions/design-backend-prompt.txt:107-112, instructions/AGENTS.md:15-25