Architecture, Security Model & Internals

Architecture, Security Model & System Internals

This chapter documents the internal architecture, multi-process isolation model, active Electron Fuses, and complete IPC contracts of sshs3. The IPC table is autogenerated directly from application source code (src/shared/types/ipc.ts) and is intended for security auditors, penetration testers, and systems engineers.

1. Three-Process Architecture & Sandboxing

sshs3 is built on Electron's multi-process model with strict separation of privilege between the presentation layer and system execution engines:

flowchart TD
    subgraph RendererProcess ["Renderer Process (Chromium Sandbox)"]
        ReactUI["React 18 Frontend (xterm.js, TabBar, DualPane)"]
        NoNode["nodeIntegration: false • contextIsolation: true"]
    end

    subgraph PreloadLayer ["Preload Layer (ContextBridge)"]
        MultiSSHApi["window.multissh (Strict Typed Facade)"]
        SafeIPC["ipcRenderer.invoke() / on()"]
    end

    subgraph MainProcess ["Main Process (Privileged Node.js)"]
        IpcBridge["IpcBridge.ts (Central IPC Router)"]
        PtyManager["SSHPtyManager (node-pty OpenSSH Engine)"]
        StorageEngine["OpenSSH SFTP v3 & AWS S3 SDK v3"]
        SecurityEngine["AskpassServer & AgentLifecycleManager"]
        Keyring["safeStorage (OS Keyring: libsecret / DPAPI / Keychain)"]
    end

    ReactUI --> MultiSSHApi
    MultiSSHApi --> SafeIPC
    SafeIPC --> IpcBridge
    IpcBridge --> PtyManager
    IpcBridge --> StorageEngine
    IpcBridge --> SecurityEngine
    IpcBridge --> Keyring

Architectural Security Guarantees

1. Zero Node.js Access in Renderer: The user interface has zero direct access to Node.js primitives (fs, child_process, net, electron). All operations must navigate the typed IPC contract.
2. Fail-Closed Security Design: If the user interface unmounts or fails to respond to host key validation (TOFU) or PIN prompts within the timeout window, the operation aborts automatically.
3. Atomic Persistence: All internal state stores (ProfileStore, SettingsStore, SessionStore) employ sequential queueMutation promises to ensure atomic disk writes via temporary files.
4. App-Wide AppAgent & Concurrent Agent Lifecycle: AgentLifecycleManager probes for a running agent via ensureAgent(). Concurrent startup callers (such as restored local shell tabs racing startup initialization) coalesce onto the same in-flight promise to prevent PTY environment race conditions. In Global PIN caching mode, the app runs a single app-wide agent (AppAgent) with a stable socket ($XDG_RUNTIME_DIR/sshs3/agent.sock or /tmp/sshs3-agent-/agent.sock, 0700), exposed to external terminals via a serialized, injection-safe # BEGIN sshs3-agent block in ~/.ssh/config.

2. Electron Fuses & Binary Hardening

During production packaging, hardware-level Electron Fuses are enforced via electron-builder.json:

3. Threat Model & Asset Protection Matrix

4. Complete Autogenerated IPC Channel Reference

5. Troubleshooting & Diagnostics Runbook