SPB Git

Repository Public

SECURITY.md 5.0 KB

# NEXTERM — Security behaviour

# Process model and entitlements

  • NEXTERM is not App Sandboxed: it must spawn the user's login shell, ssh, git, tmux and claude with the user's real environment and PTYs. Hardened Runtime is enabled; the only entitlement is com.apple.security.network.client (hook receiver on loopback, SSH is a child process). Consequence: distribution is Developer ID + notarization (not Mac App Store). See docs/RELEASE.md.
  • macOS privacy (TCC) prompts for Desktop/Documents/Downloads/removable volumes are attributed to NEXTERM when a child process touches them, exactly as with Terminal.app. NEXTERM never pre-grants anything.
  • Child processes are launched from argument arrays (LaunchSpec) — never from concatenated shell strings. The one remote-side command string (cd '<dir>' && exec tmux … over SSH) single-quotes every user value and strips control characters (SSHCommandBuilder.shellQuote, unit-tested).

# Terminal output is untrusted

  • SwiftTerm parses escape sequences; NEXTERM never interprets terminal text as application commands. Session state shown in the UI (pid, tty, cwd, foreground program) comes from the kernel (tcgetpgrp, libproc) or from OSC 7/OSC 0 title updates, which only set display strings.
  • Claude status comes exclusively from Claude Code hook events — never from scraping the screen.
  • Clickable links/paths go through SwiftTerm's UntrustedTerminalLink validation.

# Clipboard and paste

  • Multi-line pastes prompt for confirmation (Settings ▸ Behavior, on by default); bracketed paste is honoured by SwiftTerm and control bytes in pasted text are filtered (xterm disallowedPasteControls).

# SSH

  • Always /usr/bin/ssh with StrictHostKeyChecking=ask: unknown hosts prompt in the terminal, changed keys are refused by OpenSSH. There is no code path that sets StrictHostKeyChecking=no or UserKnownHostsFile=/dev/null (tested in RemoteCoreTests). Verified live on 2026-11-01: an unknown key produced OpenSSH's fingerprint prompt, "no" was answered and known_hosts was unchanged.
  • Host aliases are placed after -- so an alias can never be parsed as an option.
  • Authentication uses the user's SSH agent/keys; NEXTERM stores no passwords, passphrases or keys. Host metadata (labels, tags, groups, favourites, tmux session, remote dir) is stored in SQLite.

# Claude Code hooks (opt-in)

  • Off by default. When enabled, NEXTERM runs an HTTP receiver on 127.0.0.1:<ephemeral port> and writes ~/Library/Application Support/NEXTERM/hooks/hooks-settings.json (mode 0600) containing type: http hooks with a per-launch random bearer token. Claude sessions started by NEXTERM get --settings <that file>; ~/.claude/settings.json is never modified.
  • The receiver authenticates with a constant-time token compare, accepts only POST /hook, caps bodies at 2 MB and always returns an empty 200 — it cannot return permissionDecision, decision, updatedInput or any other directive, so it can never approve, deny or alter a tool call.
  • Turning the toggle off (or quitting) stops the receiver and deletes the settings file. Sessions already running keep the file path on their command line until restarted.

# Git

  • Read operations only, plus git worktree add and git worktree remove of a clean worktree (the API has no force parameter; dirty worktrees throw GitSafetyError). No merge, push, reset, clean, checkout or branch deletion is exposed. Dangerous UI actions ask for confirmation.
  • GIT_TERMINAL_PROMPT=0 prevents credential prompts from hanging the app.

# Process termination

  • Closing a pane/tab/window or quitting with a foreground program running asks first (tcgetpgrp says whether something other than the shell owns the PTY).

# Logging and telemetry

  • No telemetry, no network calls other than the user's own SSH/Git/Claude processes.
  • Diagnostics use os.Logger (subsystem ai.spboucher.nexterm); terminal contents are never logged. SwiftTerm's setHostLogging (raw PTY capture) is not enabled anywhere.
  • The settings file can enable diagnostic logging; it only adds lifecycle messages.

# Persistence

  • SQLite at ~/Library/Application Support/NEXTERM/nexterm.sqlite (WAL). All statements use bound parameters (PersistenceCoreTests.parameterBindingIsSafe). Stored: layouts, window geometry, pane profiles (kind, cwd, label, env overrides set by the user), settings, host metadata. Not stored: terminal scrollback, credentials, hook tokens.
  • nexterm://pane|ssh|claude|mission-control only act on already-configured hosts/panes and file-system paths that exist; nothing from a URL reaches a shell.

# Known limitations

  • The hook receiver trusts any local process holding the token (the file is 0600 and the token is per launch; a local attacker with the user's privileges could post fake events — these would only affect NEXTERM's status display, never Claude's permission flow).
  • --settings merges with the user's own hook settings; NEXTERM cannot see or control those.
Files main
Menu

Theme