Security

A modern terminal must have a conservative security stance. Dormouse won't even check whether an update is available unless you give it permission to check. If you opt in to Dormouse's push notifications and remote access, you can restrict their terminal traffic to networks you name, such as your VPN.

Dormouse holds shells, source trees, credentials, and local files. Its dependencies and release pipeline determine what code reaches a machine; remote control admits an authorized phone as a person at the keyboard; loopback listeners receive requests from pages in the user's browser.

Remote control has three roles (Roles):

• A Burrow runs your terminal sessions and decides who may reach them: Dormouse Standalone or the VS Code extension.

• A Client reaches a Burrow's terminals from a phone: Dormouse Pocket or the one-time connection page.

• A Relay introduces Clients to Burrows. Dormouse Hosted runs one at relay.dormouse.sh; you can self-host your own instead.

A Client reaches a terminal only once you approve it at the Burrow, typing there the two digits the Client shows. Each Burrow keeps its own access control and makes every access decision itself, trusting neither the Client nor the Relay; Hosted account sign-in alone grants no terminal access. All ceremony and terminal content between Burrow and Client is end-to-end encrypted with the Noise protocol, under keys no Relay holds. When the network allows it, terminal traffic runs directly between the two devices over WebRTC, so no server in between sees its timing or volume.

Features

Every feature is opt-in: one you do not use adds none of its risk. With none on, where a new install starts at Settings → Network → Nowhere, Dormouse opens nothing on its own, and you trust only the build you installed, its dependencies, and its release pipeline. One Hosted build can offer both a One-time link and a Hosted phone. The guarantees below are grouped by the features they come with, and each undefended edge and known gap names the features it concerns; one naming none holds for every install. No Relay or rendezvous can read terminal content or grant access; what each still sees is under What is not defended, and what each Settings → Network level connects to under Policy.

Guarantees

Every section the nightly audit checks opens with the guarantees its FAIL IF lines hold, or sits under one that does, and the published page gathers them here under each feature they come with: each opens with a link to that section, and Pinned by names what catches a break before the audit does.

Every install

One-time link

Hosted phone

Self-hosted Relay

How the guarantees are checked

On every pull request, tests and lints turn the mechanical half of these specs into build failures: the end-to-end channel, the installers, every loopback listener and network primitive, the workflows, and the dependency pins. The Guarantees' last column names the ones behind each row. Each lint carries a self-test that re-introduces the thing it forbids and requires the lint to go red (the lints).

Every night, and before every VS Code release, an agent per domain audits the repository against these specs (Domains): it runs every FAIL IF with evidence, then reads its domain adversarially for what no check names. A failure holds the release. Every run's result is public in the pinned Security audit status issue, and a finding's details stay private until it is fixed or 7 days old, then are published under security-audit-finding (Embargo). pgstencil audits the packages Hosted consumes in its own repository.

Every week, a canary audits the audit. It seeds already-fixed or synthetic vulnerabilities into a throwaway checkout, some beside comments that justify them, removes the tests and lints that would catch them, runs the code domains over it, and publishes only how many they caught (Canary recall).

Source of truth: root scripts in package.json; native jobs in .github/workflows/ci.yml; .github/workflows/security-audit.yaml and its release gate in .github/workflows/release.yml.

This page is docs/specs/security.md, the spec the audit runs against, published as is, with each guarantee gathered from beside the checks that hold it; the two figures above are generated from the audit's own records. It shows the guarantees for the local application, remote control, and the release pipeline; what reaches your machine is in the supply-chain disclosure.

What is not defended

• A process running as you. dor, its socket, and every file mode bound other local accounts, never a program already running under your own account; an agent holding dor has exactly the power of the person at the keyboard, and the Tool trust prompt is no boundary against it (The dor control socket).

• The Windows dor pipe carries no ACL of ours. A named pipe has no directory to harden, so an unguessable name and the token handshake are the whole of it (The dor control socket).

• A local HTML or SVG document you open can send its contents off the machine. The file viewer's content policy confines what the page loads, not where its scripts navigate (Local-file viewer).

• A mermaid sanitizer bypass in a Markdown document you open. Its diagrams reach the editor page through mermaid's strict sanitizer, not the editor's allowlist, so a bypass would run script holding the editor's save and image routes (Local-file viewer).

• A Tool trust grant on an upstream URL trusts the URL a checkout claims. Any directory whose own .git/config claims an already-granted upstream shares that grant; a folder-only grant is not shared (Dor Tool configuration).

• Output already flowing into a Tool's terminal at launch can, between Dormouse typing the command and the shell reporting it, make that run's OSC 367 open requests (Terminal output).

• A terminal can choose which of your own agent sessions resumes. Output a pane prints as Dormouse quits can name any session of a supported agent, which the next restore resumes in that pane's directory without asking; it can type nothing else (Terminal output).

• What VS Code does with the pane state it stores. Structure persists in VS Code's own storage under its modes, never a transcript (Persisted state).

• One-time link, Hosted phone, Self-hosted Relay. A compromised browser or operating system, on either end. Active XSS in the Pocket origin can use the phone's key and, with encrypted fallback storage, extract its private bytes (Client statics). Exactly two endpoints are trusted: the distributed Burrow binaries and the exact Pocket artifact the origin serves (Trust Model); a one-time session also trusts the page Hosted serves (One-time connection).

• Hosted phone, Self-hosted Relay. Presence inside an open window. While this computer holds an open presence window for a phone, it connects without a new prompt, so script running in the Pocket origin, or anyone holding the unlocked phone, reaches a terminal unprompted (Presence window).

• One-time link, Hosted phone, Self-hosted Relay. Traffic analysis. The Relay sees who talks to whom, when, how often, and how large each ciphertext is, and keystroke timing, never keystroke values (Residual metadata). An authorized session may move onto a direct connection between the two devices, after which the Relay sees that the session exists and nothing about its traffic (Direct path). Hosted's one-time rendezvous sees a handshake's timing, addresses, and frame sizes, and Cloudflare's STUN server sees every Hosted-served phone's public address, and under Anywhere this computer's (Direct path).

• Hosted phone, Self-hosted Relay. Push replay, when push is enabled. A push proves confidentiality, not freshness: a Relay that kept an envelope can re-deliver it (Push sealing).

• Hosted phone, Self-hosted Relay. Per-Burrow unlinkability, when push is enabled. One push endpoint per browser lets the Relay see every Burrow one phone registered (Residual metadata).

• Hosted phone, Self-hosted Relay. Phone-key durability. Clearing site data means pairing again. Nothing is compromised; a lost key authorized nothing on its own (Client static loss).

• One-time link, Hosted phone, Self-hosted Relay. Availability. Remote terminal access needs an online Burrow and, for new relay-backed sessions, an available Relay (Goals; keeping it up).

• Hosted phone. Whichever account first approves a live Hosted enrollment code owns the computer it enrolls; yours is then refused as already approved. That account still pairs no phone without the two digits typed here (Trust boundary).

• The bot's upstream is pinned by tag, not commit, so a hostile upstream could change what the bot runs without a diff here. Accepted: the trust equals what the harness already holds (Automated Maintainer).

• The repo-level snapshot-testing tokens are reachable by any workflow the bot can author. Accepted with rotation; each service's dashboard shows abuse (Automated Maintainer).

• The workflow audit trusts what it classifies as routine. A Renovate pin bump trusts the ref Renovate picked inside that action's repository; a bot commit under a forged human author passes when an admin push that replaces nothing carries it in, such as a cherry-pick or a rebase onto a new branch, or when it was first pushed more than a quarter ago (Automated Maintainer).

Known gaps

Gaps rather than accepted risks: we intend to close them.

• Browser-pane scripts share loopback cookies across grant ports. HTTP and WebSocket cookie headers are stripped, but document.cookie remains shared; cookie-authenticated iframe pages are unsupported (Loopback Listeners).

• Windows screenshots and pasted clipboard images are only as private as the temp directory they land in: private by default, exposed if it is shared or loosened (Browser panes).

• Neither VS Code's peer-link token, its Tool trust receipts, nor the recovery.json beside them carries a Windows ACL applied by Dormouse. They are written owner-only by unix mode, which Windows makes a no-op; standalone locks its state directory instead (Persisted state).

• Hosted phone, Self-hosted Relay. Revocation has no mechanism: nothing in the product revokes a paired phone (Revocation propagation).

• One-time link, Hosted phone, Self-hosted Relay. There is no structured audit trail covering connects, attaches, denials, or writes, so a self-hoster cannot answer "did anyone connect to my laptop last night"; each pairing records its approval, and owner-local logs report some rejections (Burrow Authorization, Trust boundary).

• A fork PR the bot checks out mid-run reaches it with that fork's instruction files. The harness pins project-instruction paths to the base branch only for the checkouts it makes before the agent starts (Automated Maintainer).

• The workflow audit's window can be evaded. A pusher-set committer date hides a commit from every later window, and a branch pushed, run with repo-level secrets in scope, and deleted before the nightly fetch is in none (Automated Maintainer).

• The audit agent can reach more than its domains need. They share AUDIT_PAT, and it shares its job with the steps that encrypt and privately file its findings. Its gh runs on that job's GITHUB_TOKEN, so it can open, edit, and comment on issues in this public repository, but cannot push or hold the Claude App's token; EMBARGO_TOKEN is out of its environment, not its reach (Domains, Embargo).

• The audit's verdict is only as honest as its result lines. The reporting step computes each verdict from the lines a domain wrote and catches a skipped rule, but not a PASS line for a check the domain never ran (Outcomes and reporting).

• The notarization password sits on a command line for up to half an hour per architecture; the remedy is known and not yet done (Desktop Releases).

• Hosted phone, Self-hosted Relay. Pocket Home Screen camera verification requires real iOS hardware (Device verification).

• Any local process can drive agent-browser's browser. Its Chrome's debugging port and its daemon's stream server take unauthenticated loopback connections, so another local account can run script there, read file:// URLs, or watch it; a web page cannot, since both refuse a foreign Origin (Loopback Listeners).

Reporting a vulnerability

Must report vulnerabilities privately through GitHub's Report a vulnerability form, visible only to the reporter and maintainers. Never open a public issue or email the maintainer. Include the version or commit, deployment (self-hosted Relay, Hosted, standalone app, or VS Code extension), and shortest reproduction. Every advisory is acknowledged with intended next steps; there is no bounty or promised response time. A coordinated-release requirement is communicated in the advisory.

• FAIL IF S268 private vulnerability reporting is disabled on the repository (gh api repos/diffplug/dormouse/private-vulnerability-reporting must report enabled: true) (rationale). Pinned by scripts/github-state-check.mjs.