SPB Git

Repository Public

SECURITY.md 6.8 KB

# SP Term — Security, sandbox and privacy

# Distribution model

SP Term is distributed outside the Mac App Store, signed with a Developer ID Application certificate, with the hardened runtime enabled and notarized by Apple when a notarization profile is available.

It is not sandboxed, by analysis rather than by convenience: the App Sandbox forbids what a terminal exists to do. A sandboxed process cannot give its children unrestricted file access, cannot run arbitrary user-installed tools with the user's own permissions, and ssh, git, package managers, compilers and editors launched from it would all inherit the container. Mac App Store terminals work around this with helper tools or restricted shells; SP Term chooses the honest model used by Terminal.app-class tools shipped outside the store.

What still protects the user:

Mechanism State
Hardened runtime On. No allow-jit, no allow-unsigned-executable-memory, no disable-library-validation, no get-task-allow, no debugger entitlement.
Entitlements Exactly one: com.apple.security.automation.apple-events, so that programs the user runs (e.g. osascript) can send Apple Events — each target still requires the user's consent in a system prompt.
TCC (privacy prompts) Not bypassed. When a program in a session touches Desktop/Documents/Downloads, the local network, etc., macOS asks on behalf of SP Term; the usage strings explain that a program in a session triggered it.
Privileges The app never asks for root, installs no helper, no launch agent, no kernel/system extension, and never touches SIP or Gatekeeper settings. sudo is whatever the user types in a shell.
Child processes Started through forkpty + posix_spawn(SETEXEC, CLOEXEC_DEFAULT): they inherit no file descriptor of the app (tested), get default signal handling and a cleaned environment (DYLD_*, XPC_* and debugging variables are stripped).

# Untrusted terminal output

Program output — including output from remote hosts — is treated as untrusted input.

  • Escape sequences: parsed by the engine; malformed/unknown sequences are ignored (conformance + fuzz tests).
  • Window title (OSC 0/2): control characters removed, length capped.
  • Clipboard (OSC 52): write is ask by default (the text and the requesting program are shown), read is deny by default. Both are settings.
  • Links (OSC 8 and detected URLs): http, https, mailto open directly on ⌘-click; file: is only revealed in Finder, never launched; javascript:/data: are blocked; any other scheme asks first.
  • Notifications: only process name and duration are shown, never terminal text.

# Paste and typed input

  • Several lines → confirmation with a preview where control characters are made visible (configurable).
  • Text containing escape sequences or the bracketed-paste terminator → always asks, and the default action pastes a sanitized version.
  • Sanitized pastes never end with a line break, so nothing runs before the user presses Return.
  • Dropped files insert shell-escaped paths (round-trip tested against a real shell with hostile names).

# Broadcast input

Off at every launch (never persisted); enabling it shows which sessions will receive input and requires a confirmation; a full-width banner and coloured pane borders stay visible; lines that look destructive or use sudo are held for the other panes until the user types the confirmation phrase; cancelling clears the line in the other panes. Automatic terminal replies are never broadcast. Limit: the pane being typed in is a normal terminal — the line runs there as typed; the guard protects the fan-out.

# SSH

SP Term builds an argument vector for /usr/bin/ssh and lets OpenSSH do everything else. Every field is validated against an allow-list (no leading -, no whitespace, no shell metacharacters); the builder never emits StrictHostKeyChecking, UserKnownHostsFile, BatchMode or password options; extra -o options go through an allow-list. Host key verification is therefore OpenSSH's interactive prompt in the terminal; SP Term never answers it. Private keys are never opened. Passwords and passphrases are typed into the PTY and are neither captured nor logged. Opening a host runs ssh only — no command is sent to remote hosts.

# Assistant (SP Intelligence)

Off by default. Guarantees enforced by types and tests:

  1. No request without a preview: AIClient.send only accepts an ApprovedPreview, which can only be made from a ContextPreview the user has seen.
  2. The preview is the exact payload (destination, model, byte count, masked text). Secrets are always masked first.
  3. Terminal text is attached only when the user selects Selected text or Last 60 lines.
  4. Local-only mode refuses every non-loopback destination before any I/O; plain HTTP to a remote host is refused.
  5. API keys are stored in the Keychain (ai.spboucher.spterm.ai), sent in a header, and wrapped in a type whose description is redacted.
  6. Suggested commands are text. Insert types them without Return. Review & Run goes through the consent gate: full command, target, host, directory, risk reasons; destructive, sudo, network-transfer and multi-host commands need a typed phrase.

# Data at rest

~/Library/Application Support/SP Term/ is created 0700; files are 0600 and written atomically. Stored: settings, layouts (titles, directories, session kinds), snippets, SSH profile metadata, provider metadata, and — only if enabled — a history of commands run from snippets/assistant/broadcast with secrets masked. Not stored: terminal output, keystrokes typed at prompts, API keys, SSH credentials. Private mode stops layout and history writes and deletes the saved layout.

# Plugins and extensions

There is no plugin system and no scripting bridge: SP Term loads no third-party code and exposes no automation interface that could run commands. If one is added later, the policy is: explicit installation by the user, signed bundles only, a declared capability list shown at install time, no access to terminal content or to "run a command" without the same consent gate as the assistant, and nothing enabled by default.

# Updates

No update mechanism is active: no feed URL exists for this build, and shipping a self-updater without a signed, reliable feed would be a liability. Sparkle (EdDSA-signed appcasts) is the intended mechanism once a distribution URL exists.

# Known limits

  • The risk analyzer and the secret redactor are pattern based: safe means "no known risky pattern", and an unusual secret format can pass unmasked — the preview exists so the user can check.
  • A program running in a session has the user's full permissions; SP Term does not confine it.
  • Exported session files contain whatever was on screen (masked by default); they are created 0600.
Files main
Menu

Theme