Privacy and Security

Documentation in progress

Some sections are still incomplete.

ThinkTerm collects nothing about you, your machines or how you use it. There is no telemetry, no analytics and no tracker, and the project has no server for any of that to reach. Apart from one update check, everything ThinkTerm sends over a network is something you started.

What leaves the machine on its own

Only the update check. While the desktop app is running it asks GitHub's release API whether a newer release exists: the first time about ten seconds after it first starts, and from then on once per check_for_updates_interval_seconds, which is a day unless you change it. The command-line tools, the TUI and the session server never check on their own.

The request is anonymous. It carries no credentials unless you set THINKTERM_UPDATE_TOKEN yourself, which is only useful for reaching a private fork. The app never reads GITHUB_TOKEN, so a token you exported for other tools is not sent by a check you did not run. GitHub sees the request as it sees any other; the people who make ThinkTerm do not.

check_for_updates = false in the config turns it off. Updates covers the rest of the update flow.

What leaves the machine when you use it

What you do	Where it goes
Connect over SSH, Mosh or ThinkTerm Connect	The host you connect to
Leave Detect OS or Detect remote programs on for a host	That host, over the same connection: a check of its distribution, or ThinkTerm's shell integration copied into ~/.config/thinkterm/ there
Open a Note that shows an image from a web address	The server that address names
Agree to update a remote server	That host downloads the install script and the release from GitHub
Run thinkterm update, or press Install Update	GitHub, for the release
Turn on browser access	Browsers that open a link you made

Images in Notes load from the web by default, and loading one tells that server your address, as any web page would. note_remote_images_enabled = false stops it.

A plugin is a program you installed, and it can use the network like any other program. The Stocks plugin in ThinkTerm's source, for example, fetches quotes from Yahoo Finance. No plugin is part of the downloads; see Plugins.

What is kept on this machine

ThinkTerm keeps its state in your user account: Spaces, Projects and Threads, the SSH host book, snippets, recent commands, settings. Configuration lists where each lives on each system. A Notes Vault is a folder you chose, holding ordinary Markdown files.

Terminal output is held in memory, by the app or by the session server, and is not written to disk.

On macOS and Linux, the files that matter most are written readable by you alone, mode 0600:

• secret.key, the key that encrypts saved SSH passwords
• the snippets file
• the files of a backup you export
• a browser listener's token file and its certificate and private key
• a new Note ThinkTerm creates, unless the folder gives it a mode of its own

That stops other accounts on the machine. It does not stop anything running as you — a sync client, a backup job, a plugin — which reads a 0600 file as easily as ThinkTerm does. Remote explains what that means for saved passwords in particular.

Windows has no equivalent mode to set, so these files take the permissions of the folder they are in. For a default user profile that is you, SYSTEM and the Administrators group. To keep credentials out of a roaming profile, which Windows copies to a profile server at sign-out on some domains, the SSH host book and its key are kept under %LOCALAPPDATA%\ThinkTerm\ssh\, and a browser listener's certificate under %LOCALAPPDATA%\thinkterm\web-tls\.

The browser page

Browser access is off until you turn it on. When it is on, the page, its scripts and its fonts are all served by your own machine; the page makes no request to anyone else, and nothing about its use is collected.

A browser is admitted by a token you mint, delivered as part of a link. The page takes the token out of the address bar as soon as it loads and keeps it in that tab's sessionStorage, which the browser discards when the tab closes. Whoever holds the link has a shell as you on that machine, so it is a credential like an SSH key.

The server stores tokens only if a token_file is configured; otherwise they live in memory and a restart forgets them. What it writes for each is a SHA-256 digest of the token, never the token itself — so a copied file admits nobody — with its name, when it was made, when it expires, when it was last used, and a coarse description of the browser that last used it, such as "iPhone · Safari". No address of any device is recorded, and the server's log names the token that was admitted rather than who used it.

A self-signed certificate is made only when a listener is bound off loopback without a certificate of your own. It names the machine's hostname and its addresses, which anyone who connects to that port can see — that is what a certificate is for.

The page keeps your choices for it — language, theme, font size, colour scheme, the Space it was showing, panel widths, recent palette picks — in the browser's localStorage, on that device. Clearing the site's data forgets them. Web covers who can reach the port and how to check the certificate.

Permission prompts on macOS

macOS attributes what a program does to the app that started it. ThinkTerm starts your shell, and your shell starts everything you run, so a command that touches something protected — find walking through the folder where Contacts are stored, a tool that opens the camera — produces a prompt that names ThinkTerm. The prompt's own text says this: An application launched via ThinkTerm would like to access…. ThinkTerm itself has no code that reaches for your contacts, camera, location or anything of the kind.

Local terminals kept in a background session server are started by that server, not by the app, and it asks under its own name, thinkterm-mux-server. A folder you already allowed for ThinkTerm may need allowing again for the server. Configuration describes how ThinkTerm tells you which of the two was refused.

Plugins

A plugin runs as you, with your permissions. ThinkTerm shows nothing of it outside the sidebar, but there is no sandbox around the program itself: it can read your files, use the network and run other programs, and on a terminal reached over SSH it can ask ThinkTerm to do the same on that host. Install one the way you would install any other program. Plugins has the details.

Reporting a security problem

Report it privately, through GitHub's private vulnerability reporting: open the repository's Security tab and choose Report a vulnerability, or go to github.com/RoversX/ThinkTerm/security/advisories/new. Please do not open a public issue, discussion or pull request about it.

Include as much of this as you can:

• the version, from thinkterm -V, and your operating system
• the part involved — the desktop app, the session server, browser access, SSH or Mosh connections, the plugin server
• steps to reproduce it, or a proof of concept
• what an attacker can do, and what they need first

You should hear back within a week. A fix for a complex problem can take longer, and you will be told how it is going. When the fix is released the advisory is published and credits you, unless you would rather not be named; until then, please keep the details private.

Only the latest release is supported, and fixes go into the next one. Check that the problem still happens there before reporting it.

What counts

All the code in the repository is in scope, including what ThinkTerm inherited from WezTerm. If a problem affects WezTerm as well, say so, so that it can be reported upstream too.

These are not vulnerabilities in ThinkTerm:

• What an installed plugin can do. It is a program you installed, running as you.
• Access by someone who already holds a valid browser token, can read your ThinkTerm data, or can log in as you. Tokens and the key behind saved passwords are credentials.
• Problems in programs ThinkTerm only runs, such as your shell, ssh or mosh.

Builds from elsewhere

All of the above describes ThinkTerm's source and the builds its own release process publishes on GitHub. A build obtained anywhere else may have been changed to behave differently.

Related

• Install — what the install script downloads and checks
• Web — turning browser access on, and the link that admits a browser
• Plugins — what an installed plugin can reach
• Remote — saved SSH passwords and how they are protected
• Configuration — where ThinkTerm's files live