Repository navigation
Description
Problem
Agent sign-in works only where the helper can open a Unix socket (macOS, Linux). On Windows there is no helper at all, so a local program asking Keytray to fill a code gets "agent is not running". A WSL shell has the same problem: the browser is the Windows Chrome, but the helper and CLI only know the Linux socket path.
Evidence
native/keytray-agent.py:100createssocket.socket(socket.AF_UNIX, ...). CPython on Windows has noAF_UNIX:(Python 3.14 on Windows 11.)> python -c "import socket;print(hasattr(socket,'AF_UNIX'))" Falsenative/install.shregisters the host only under macOS and Linux browser folders; nothing writes the Windows registry keys (HKCU\Software\Google\Chrome\NativeMessagingHosts\com.keytray.agent) that Chrome on Windows reads.native/keytray-agent-cli.py:61connects only to the Unix socket, so on Windows it fails, and inside WSL it looks for~/.local/share/Keytray/agent.sock, which never exists because the browser runs on the Windows side.- On macOS the same request works (
statusreturnsok), but it can only fill a tab in that Mac's own browser. That is by design and stays. lib/agent.ts:54isAllowedUrlmatches exact hosts or subdomains only. There is no way to say "every site": an entry*is kept bynormalizeAllowlistbut then never matches.
Decision
Each computer serves its own browser. A program on Windows (or in WSL on that Windows computer) talks to a helper on the same computer, which hands the request to the Keytray extension in that computer's browser. The code never leaves the extension, as today.
Transport on Windows: a named pipe with a shared-key handshake, Python standard library only (multiprocessing.connection.Listener(family="AF_PIPE", authkey=...)):
- Pipe
\\.\pipe\keytray-agent-<windows user name>. - Key: 32 random bytes in
%LOCALAPPDATA%\Keytray\agent.key, made by the helper on first start. That folder is readable only by the user (inherited profile ACL), which plays the role of the socket's mode 0600. A client without the key fails the HMAC handshake before any request is read. - Only
send_bytes/recv_bytes(neversend/recv, which unpickle). One request per connection, 65,536 bytes max, same JSON request and reply as the socket. - WSL: the CLI sees it runs under WSL (
/proc/sys/kernel/osreleasecontainsmicrosoft) and re-runs itself with the Windows Python, so the call reaches the Windows helper.KEYTRAY_NO_WSL_REEXEC=1turns that off.
All sites option: an allowlist entry * means every https site. Options gets an "Allow all sites" button next to "Reset to default". The rate limit (10 requests per 10 minutes), the https-only rule, the frame check, fill-never-submits and "replies never carry a code" all stay. The default list is unchanged for new installs.
Rejected
- A helper on one computer serving a browser on another (over ssh or a private network): the code, or control of a tab, would cross computers. New network surface, and nothing gained, because each computer already has the extension signed in to the same mail.
- Returning the code to the caller: breaks the rule that the agent never sees the code. A program fooled by a web page could leak it.
- TCP on 127.0.0.1 with a token: works, but any local process can reach the port. The named pipe plus key handshake is the same idea with less surface, and the pattern is already proven in a sibling extension.
- A separate Linux helper inside WSL: there is no browser with Keytray in WSL, so it would have nothing to talk to.
Plan
1. native/keytray-agent.py
WINDOWS = os.name == "nt".appdir():KEYTRAY_APPDIRif set, else%LOCALAPPDATA%\Keytray.pipe_name():KEYTRAY_AGENT_PIPEif set, else\\.\pipe\keytray-agent-+getpass.getuser().load_key(): createagent.keywithos.open(..., O_CREAT|O_EXCL, 0o600)and 32 bytes ofos.urandom, else read it.serve_pipe():Listener(address=pipe, family="AF_PIPE", authkey=key). Loop onaccept(); an exception (bad handshake) drops that client and keeps listening. Each connection:recv_bytes(65536)once, same parse and relay ashandle_client,send_bytesthe reply, close. If the Listener itself cannot be created (another helper owns the pipe), keep serving stdio and stop trying the pipe.- Factor the shared part of
handle_clientintorelay(raw_bytes) -> dictso the socket and the pipe use the same code. The Unix path is otherwise unchanged. main()startsserve_pipeon Windows,serveelsewhere. On Windows, exit removes nothing (the pipe goes away with the process).
2. native/keytray-agent-cli.py
- Same
appdir()/pipe_name()helpers. On Windows: read the key,Client(pipe, family="AF_PIPE", authkey=key),send_bytes,recv_bytes, with the same 140 s timeout (poll the connection for the reply). Missing key or no pipe gives the existing "host is not running" message. - WSL re-exec before anything else: find
py.exe(with-3) orpython.exe,wslpath -wthis file, run it with the same argv and return its exit code.KEYTRAY_NO_WSL_REEXEC=1skips it;KEYTRAY_OSRELEASEpoints the check at another file for tests. - Output and exit codes unchanged.
3. native/windows/install.ps1 (new) and native/windows/uninstall.ps1 (new)
- Find a real Python (skip the WindowsApps store stub; check
py, thenpython). - Copy
keytray-agent.pyandkeytray-agent-cli.pyto%LOCALAPPDATA%\Keytray. - Write
keytray-agent.cmd(@echo off+"<python>" -u "<host>" %*) andkeytray.cmd(same Python, runs the CLI), so host and CLI always use the same interpreter (the key handshake changed between Python versions). - Compute the dev extension id from
EXTENSION_KEYinwxt.config.tsthe same wayinstall.shdoes (sha256 of the DER key, first 32 hex chars mapped 0-f to a-p). Writecom.keytray.agent.jsonwithallowed_origins= store id + dev id + any ids passed as arguments. - Set the default value of
HKCU:\Software\Google\Chrome\NativeMessagingHosts\com.keytray.agent, and the same under Microsoft Edge and BraveSoftware\Brave-Browser, to that manifest path. - Print the CLI path and "turn on Agent sign-in in Options".
- Uninstall removes the three registry keys and the copied files, and keeps
agent.keyunless-Allis passed.
4. Allow all sites
lib/agent.ts: exportALL_SITES = '*'.normalizeAllowlistkeeps a bare*as is (today it would survive only by accident; make it explicit and tested).isAllowedUrlreturns true for any https host when the list contains*.entrypoints/options/App.tsx: an "Allow all sites" button beside "Reset to default" that saves['*'], and a short line under the list when*is in it: "Every https site. The rate limit still applies."tests/agent.test.ts:*allowshttps://example.organd subdomains, still refuseshttp://,normalizeAllowlistkeeps*,runAgentCommandfills on a non-listed site when the list is['*'], andopen_linkopens a link on any https host with*.
5. native/test-host.py
- Run on every OS. On Windows use a temp
KEYTRAY_APPDIRand a uniqueKEYTRAY_AGENT_PIPE, wait foragent.key, skip the 0600 mode check, and add a check that a client with a wrong key is refused. SetKEYTRAY_NO_WSL_REEXEC=1.
6. CI (.github/workflows/ci.yml)
- Job
check(the required check) keeps its name and addspython3 native/test-host.py. - New job
native-windowsonwindows-latest:python native/test-host.py.
7. Docs
docs/agent-protocol.md: a Windows section (pipe name, key file, handshake, framing) and the WSL note.README.md"Agent sign-in": Windows install (powershell -ExecutionPolicy Bypass -File native\windows\install.ps1), the WSL note, and the "Allow all sites" option with what it means.
How it is checked
pnpm compile,pnpm test(new allowlist tests),python native/test-host.pyon Windows and on Linux/WSL, CI green on both jobs.- On a real Windows computer: run
install.ps1, reload the extension, turn on Agent sign-in,keytray.cmd statusreturnsok. Then on a GitHub page that asks for an emailed code:pending <tab>shows the field,fill_code <tab> --wait 120fills it, the agent clicks the submit button, the page moves on. The code never appears in any output. - From WSL on that computer: the same
statusthrough the re-exec. - macOS: unchanged path,
statusstillok.
Activity
MehdiMamas commentedon Nov 16, 2026
Plan changes after review
install.ps1resolves the real interpreter path (sys.executable) and writes it into bothkeytray-agent.cmdandkeytray.cmd. The WSL re-exec runs the installed%LOCALAPPDATA%\Keytray\keytray.cmdthroughcmd.exe(notpy -3on the repo copy), so the host and the client always use the same Python. That matters because themultiprocessingkey handshake changed in 3.12.conn.poll(140)beforerecv_bytesand treatsEOFErrorandOSErroras "closed early". The host waits withpoll(10)beforerecv_bytes(65536). Known limit, written in the protocol doc: a local process that connects and never answers the handshake can stallaccept(). It needs no key, and it is the same class of problem as a local process filling the Unix socket backlog.os.replace. A key that is not 32 bytes counts as missing.test-host.pywaits forstatusto answer, not for the file to appear.*, any https tab is allowed. The code goes only to frames on the tab's own host or a subdomain of it, or to frames on a listed host. A link opens only when its host is the tab's host or a subdomain of it, or a listed host. Tests cover both.install.sh.actions/setup-pythonwith 3.9 and 3.13, runstest-host.py, theninstall.ps1, areg querycheck, andinstall.ps1 -Uninstall.-Uninstallswitch oninstall.ps1, not a second script. Registry keys for Chrome and Edge only. NoKEYTRAY_OSRELEASE: the WSL check is a small function.MehdiMamas commentedon Nov 16, 2026
Status
Merged: #42 (all sites,
*), #43 (Windows named-pipe helper, WSL re-exec, Windows CI on Python 3.9 and 3.13).statusinstall.ps1run*comes only with the next Store releaseinstall.ps1runAllowlist setting
otpState, fieldsettings.agentAllowlist).github.com, google.com, vercel.com, apple.com(read withstatuson the laptop and the Mac).*once "Allow all sites" is clicked on each unpacked build. Not done yet: that page cannot be reached by browser automation.Still open: the real fill test (a GitHub emailed code filled into a GitHub page on the desktop), after the reload.
MehdiMamas commentedon Nov 16, 2026
Plan 2: computer config file, and a fix for all sites
Hole found in #42 (fix first)
With
*,fill_codeputs the newest code from any sender into any https tab. A phishing page that a program is tricked into opening would receive, for example, a real GitHub code. With a plain list this cannot happen, because only listed sites get codes.Fix:
*gets only a code whose sender matches the tab's site. The sender's email domain is cut to its base: the last two labels, or the last three forco.uk-style suffixes. For example,noreply@github.comgivesgithub.com, andaccounts.google.comgivesgoogle.com. The tab's host must equal that base or be a subdomain of it.fill_codekeeps waiting, andpendingshows none.open_linkalready needs the link's host to be on the tab's site; that stays.Config file per computer
config.jsonin the helper's data folder. Windows:%LOCALAPPDATA%\Keytray\config.json. macOS:~/Library/Application Support/Keytray/config.json. Linux:${XDG_DATA_HOME:-~/.local/share}/Keytray/config.json.{"agentSignIn": true|false, "allowedSites": ["*"] | ["github.com", ...]}. Anything else in the file is ignored. A file that does not parse, or has wrong types, counts as no file.native/keytray-agent.py): a message from the extension{"kind":"getConfig"}is answered with{"kind":"config","config":<object or null>}. The file is read fresh each time. Replies to agent requests are unchanged.entrypoints/background.ts):connectNativefails, nothing retries, and there is no load for users without the helper. If it answers with no config, disconnect.agentEnabled = agentSignIn,agentAllowlist = normalizeAllowlist(allowedSites)(an empty list keeps the default list),agentConfigFromFile = true.agentConfigFromFileis set, the switch, the list and the buttons are disabled, with the line "Set by this computer's Keytray config file."install.shandinstall.ps1gain an optional--allow-all/-AllowAllthat writes the file withagentSignIn: trueandallowedSites: ["*"]. Without it, no file is written.Trust argument
Tests
tests/agent.test.ts: under*, a tab not on the list gets only a matching-sender code. A GitHub code is refused onhttps://evil.exampleand filled onhttps://github.com/loginwhengithub.comis not listed. A listed tab still gets the newest code. Base-domain cases:co.uk, subdomains.native/test-host.py:getConfigreturns null with no file, the object with a valid file, and null with a broken file.MehdiMamas commentedon Nov 16, 2026
Review of plan 2: not built as written
A fresh review found real holes, so nothing from plan 2 is built yet.
agentSignInandallowAll.firebaseapp.com,github.io,vercel.app,pages.dev,web.app,com.au,co.jp. Fix: use the Public Suffix List with private domains on (for example tldtsgetDomain(..., {allowPrivateDomains: true})). A sender whose registrable domain is itself a private suffix matches nothing.fill_codewaits. The tab's URL is read once before a wait of up to 120 s. Fix: read the tab URL again on each try, pick the entry first, then require every frame that receives the code to be on that entry's sender site.pendingandfill_code, so a newer mail from another domain cannot hide the right code.Lesser points:
<...>, not the first@: a display name can contain a fake address.open_linktoo.dmarc=pass.Until this is fixed,
*in the current code (from #42) must not be used or released. It is not set on any computer and has not been released.Config file review fixes: probe only at start, own the all-sites star…
Config file second review: trust wording, owner and mode check, flag …
Agent sign-in: per-machine config file (on/off and all sites only) (#45)