security.md

Security

• See docs/specs/glossary.md for Session, Pane, Surface, and remote-role vocabulary.
• Owns the features Dormouse offers, what it does not defend, the gaps it knows about, and how all of it is checked. Each guarantee sits beside the checks that hold it, in the domain spec, and is gathered here when published.
• Defers every mechanism to the spec that owns it, and every audited check to the specs the audit's domains own (Domains). Published at https://dormouse.sh/security; docs/specs/website-docs.md owns which entries each page shows.

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.

Feature	What Dormouse opens on its own	What you trust beyond this computer
One-time link. A Hosted build, the one Dormouse distributes, at Local networks only or Anywhere. You open a link in Settings for one phone; no account.	While a link is open, a socket to relay.dormouse.sh for its handshake (Hosted rendezvous). Terminal traffic goes only directly between the two devices.	The phone, and the page Hosted serves it, so Hosted's deployment pipeline and Cloudflare account (One-time connection).
Hosted phone. A Hosted build at Local networks only or Anywhere, enrolled with your Hosted account (Burrow enrollment), with Pocket paired.	A socket to Hosted's Relay at relay.dormouse.sh, for handshakes, pairing, and any push you turn on. Terminal traffic goes directly when it can, otherwise through Hosted under Anywhere; under Local networks only, only directly.	The phone, and the Pocket app Hosted serves it, so Hosted's deployment pipeline and Cloudflare account (Trust Model).
Self-hosted Relay. A self-host build, compiled from source and pointed at your own Relay (Relay origin), at Anywhere, through your Relay. The default installer keeps that Relay on your tailnet.	A socket to your Relay, for handshakes, pairing, and any push you turn on. Terminal traffic goes directly when it can, with no STUN server, otherwise through your Relay.	The phone, and the Pocket app your Relay serves it.

Guarantees

Every section the nightly audit checks opens with the guarantees its own FAIL IF lines hold, 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.

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).

Every night, a second-opinion audit runs the same prompts on Codex, another vendor's model, published beside the audit but never gating a release; the canary measures both (Second-opinion audit).

Every month, and before releases that change remote control or Hosted, a red team reads the code and these guarantees without the FAIL IF lines, on Claude and on Codex, for what the checks themselves miss (Red team); each pass is a red-team issue.

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.

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).
• One-time link, Hosted phone, Self-hosted Relay. Another Windows account can hold a dead VS Code broker's pipe name silently while one of its processes reuses that broker's pid, which keeps windows waiting for a broker that is gone (The VS Code peer link).
• A local HTML or SVG document you open, or confirm from a document link, 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, image, and document-open routes; an open of a page that runs its own scripts still waits on Dormouse's own dialog (Local-file viewer, Terminal output).
• 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. Forged attention notices, when push is enabled. The Relay or the browser's push service can make Pocket show its content-free "a terminal needs attention" notice at will (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. The voice provider keeps what managed voice speaks until Dormouse deletes it. ElevenLabs stores each spoken label in its speech history; Dormouse deletes it there, usually within minutes, but no bound is guaranteed, and deleting it need not erase the provider's backups or moderation records (Account boundary).
• Hosted phone. Whichever account first approves a live Hosted enrollment code, with the two digits its computer shows, owns that computer; yours is then refused as already approved. Approving takes those digits, so a link alone approves nothing, but a stranger can read you theirs. That account still pairs no phone without the two digits typed here (Trust boundary). Approving a stranger's code lets their computer add passkeys to your account, filling it and signing you out, until you remove them on the account page; a voice code spends your daily voice allowance until you turn Natural Voice off.
• Hosted phone, Self-hosted Relay. Whoever first redeems a live setup QR adds a passkey to your account and is signed in; on Hosted, until the account page removes it. That 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.

• Shell-specific Windows command quoting does not protect every native batch handoff. PowerShell can strip quotes around a no-space argument before a .cmd target parses it, turning an ampersand into command syntax. This affects argv Tools launched in new Sessions, preview retargets, and restored commands; falling back from portable quoting to a new Session does not repair it. The portable form used for paste and existing-prompt commands refuses these arguments (Dor Tool configuration).
• 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 and endpoint, 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).
• One-time link, Hosted phone, Self-hosted Relay. No independent third party has reviewed remote control's cryptography. Dormouse's Noise integration, passkey (WebAuthn) channel binding, key storage, and push sealing are checked only by this project's own tests, lints, and nightly audits, which AI agents run (Noise suite).
• Self-hosted Relay. Anyone who can reach your Relay can hold off sign-in by flooding it: unauthenticated requests share the capped pool of sign-in challenges, evicting a real one before its passkey prompt is answered. The default install admits only your tailnet (Network posture (self-hosted)).
• Hosted phone, Self-hosted Relay. A user-verification demand raised after enrollment can be lost if this computer cannot save it. The Burrow keeps the raise in memory and retries the save at each start, but a relaunch while saving keeps failing starts it at presence until the Relay repeats the demand (Trust boundary).
• Hosted phone, Self-hosted Relay. Revocation has no mechanism: nothing in the product revokes a paired phone (Revocation propagation); a phone can only forget its own pairings, with Pocket's Sign out and forget this phone.
• 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).
• A hand- or bot-edited lockfile skips the cooldown. Nothing checks the age of a version a lockfile edit adopts (Cooldown and alerts).
• 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).
• A bundled theme's disclosed version and license are unchecked. A test pins which theme extensions are disclosed, not what each record says (Disclosure).

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.