Skip to content

Agent sign-in on Windows and WSL, plus an all-sites option #41

Open

Description

@MehdiMamas

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:100 creates socket.socket(socket.AF_UNIX, ...). CPython on Windows has no AF_UNIX:
    > python -c "import socket;print(hasattr(socket,'AF_UNIX'))"
    False
    
    (Python 3.14 on Windows 11.)
  • native/install.sh registers 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:61 connects 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 (status returns ok), but it can only fill a tab in that Mac's own browser. That is by design and stays.
  • lib/agent.ts:54 isAllowedUrl matches exact hosts or subdomains only. There is no way to say "every site": an entry * is kept by normalizeAllowlist but 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 (never send / 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/osrelease contains microsoft) and re-runs itself with the Windows Python, so the call reaches the Windows helper. KEYTRAY_NO_WSL_REEXEC=1 turns 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_APPDIR if set, else %LOCALAPPDATA%\Keytray. pipe_name(): KEYTRAY_AGENT_PIPE if set, else \\.\pipe\keytray-agent- + getpass.getuser().
  • load_key(): create agent.key with os.open(..., O_CREAT|O_EXCL, 0o600) and 32 bytes of os.urandom, else read it.
  • serve_pipe(): Listener(address=pipe, family="AF_PIPE", authkey=key). Loop on accept(); an exception (bad handshake) drops that client and keeps listening. Each connection: recv_bytes(65536) once, same parse and relay as handle_client, send_bytes the 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_client into relay(raw_bytes) -> dict so the socket and the pipe use the same code. The Unix path is otherwise unchanged.
  • main() starts serve_pipe on Windows, serve elsewhere. 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) or python.exe, wslpath -w this file, run it with the same argv and return its exit code. KEYTRAY_NO_WSL_REEXEC=1 skips it; KEYTRAY_OSRELEASE points 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, then python).
  • Copy keytray-agent.py and keytray-agent-cli.py to %LOCALAPPDATA%\Keytray.
  • Write keytray-agent.cmd (@echo off + "<python>" -u "<host>" %*) and keytray.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_KEY in wxt.config.ts the same way install.sh does (sha256 of the DER key, first 32 hex chars mapped 0-f to a-p). Write com.keytray.agent.json with allowed_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.key unless -All is passed.

4. Allow all sites

  • lib/agent.ts: export ALL_SITES = '*'. normalizeAllowlist keeps a bare * as is (today it would survive only by accident; make it explicit and tested). isAllowedUrl returns 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: * allows https://example.org and subdomains, still refuses http://, normalizeAllowlist keeps *, runAgentCommand fills on a non-listed site when the list is ['*'], and open_link opens a link on any https host with *.

5. native/test-host.py

  • Run on every OS. On Windows use a temp KEYTRAY_APPDIR and a unique KEYTRAY_AGENT_PIPE, wait for agent.key, skip the 0600 mode check, and add a check that a client with a wrong key is refused. Set KEYTRAY_NO_WSL_REEXEC=1.

6. CI (.github/workflows/ci.yml)

  • Job check (the required check) keeps its name and adds python3 native/test-host.py.
  • New job native-windows on windows-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.py on 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 status returns ok. Then on a GitHub page that asks for an emailed code: pending <tab> shows the field, fill_code <tab> --wait 120 fills 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 status through the re-exec.
  • macOS: unchanged path, status still ok.

Activity

  1. MehdiMamas commented on Nov 16, 2026

    @MehdiMamas
    OwnerAuthor

    Plan changes after review

    1. One interpreter per computer. install.ps1 resolves the real interpreter path (sys.executable) and writes it into both keytray-agent.cmd and keytray.cmd. The WSL re-exec runs the installed %LOCALAPPDATA%\Keytray\keytray.cmd through cmd.exe (not py -3 on the repo copy), so the host and the client always use the same Python. That matters because the multiprocessing key handshake changed in 3.12.
    2. Timeouts. The client waits with conn.poll(140) before recv_bytes and treats EOFError and OSError as "closed early". The host waits with poll(10) before recv_bytes(65536). Known limit, written in the protocol doc: a local process that connects and never answers the handshake can stall accept(). It needs no key, and it is the same class of problem as a local process filling the Unix socket backlog.
    3. Key file. Written to a temp file and moved into place with os.replace. A key that is not 32 bytes counts as missing. test-host.py waits for status to answer, not for the file to appear.
    4. All sites keeps the frame and link checks tight. With *, 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.
    5. Helper survives a lost pipe. If the pipe cannot be created (an old helper still holds it), retry every 5 s instead of giving up. Manifest written as UTF-8 without a BOM. The dev id is computed by running the same Python snippet as install.sh.
    6. CI. The Windows job uses actions/setup-python with 3.9 and 3.13, runs test-host.py, then install.ps1, a reg query check, and install.ps1 -Uninstall.
    7. Cut. Uninstall is a -Uninstall switch on install.ps1, not a second script. Registry keys for Chrome and Edge only. No KEYTRAY_OSRELEASE: the WSL check is a small function.
  2. MehdiMamas commented on Nov 16, 2026

    @MehdiMamas
    OwnerAuthor

    Status

    Merged: #42 (all sites, *), #43 (Windows named-pipe helper, WSL re-exec, Windows CI on Python 3.9 and 3.13).

    Computer Helper status Notes
    Windows laptop, from WSL install.ps1 run ok (through the Windows helper) Store build; * comes only with the next Store release
    macOS unchanged ok unpacked build rebuilt from main; needs a reload to show "Allow all sites"
    Windows desktop install.ps1 run not running yet unpacked build rebuilt from main; needs a reload in chrome://extensions, then Agent sign-in on

    Allowlist setting

    • Where: Keytray Options, section "Agent sign-in", list of sites (stored in the extension's local storage, key otpState, field settings.agentAllowlist).
    • Before: github.com, google.com, vercel.com, apple.com (read with status on the laptop and the Mac).
    • After: * 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.

  3. MehdiMamas commented on Nov 16, 2026

    @MehdiMamas
    OwnerAuthor

    Plan 2: computer config file, and a fix for all sites

    Hole found in #42 (fix first)

    With *, fill_code puts 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:

    • A tab on a listed site keeps today's behaviour.
    • A tab allowed only by * 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 for co.uk-style suffixes. For example, noreply@github.com gives github.com, and accounts.google.com gives google.com. The tab's host must equal that base or be a subdomain of it.
    • When no sender matches, the tab gets no code: fill_code keeps waiting, and pending shows none.
    • open_link already needs the link's host to be on the tab's site; that stays.

    Config file per computer

    • Where: config.json in 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.
    • Contents: {"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.
    • Helper (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.
    • Extension (entrypoints/background.ts):
      • Agent sign-in on: after each connect, ask for the config.
      • Agent sign-in off: at startup, try the helper once. If it is missing, connectNative fails, nothing retries, and there is no load for users without the helper. If it answers with no config, disconnect.
      • When a config comes back, apply it: agentEnabled = agentSignIn, agentAllowlist = normalizeAllowlist(allowedSites) (an empty list keeps the default list), agentConfigFromFile = true.
      • When no config comes back and the flag is set, clear the flag and keep the values.
    • Options: while agentConfigFromFile is set, the switch, the list and the buttons are disabled, with the line "Set by this computer's Keytray config file."
    • Unchanged: defaults for everyone, the rate limit (10 per 10 minutes), https only, the frame rule, fill never submits, and replies never carry a code.
    • Install scripts: install.sh and install.ps1 gain an optional --allow-all / -AllowAll that writes the file with agentSignIn: true and allowedSites: ["*"]. Without it, no file is written.

    Trust argument

    • The file sits in the user's own data folder, so only that OS user (or an admin) can write it.
    • That same user can already register a native host, change the extension's storage while the browser is closed, or install the extension's helper with any settings. The file adds no new kind of access.
    • What it protects against: web pages. A page cannot write the file or reach the helper. Other OS users: the file and folder are per-user.
    • What it does not protect against: malware running as the same user. Before, turning agent sign-in on needed a click in the browser. Now a local program can write the file and turn it on. Even then, the program never sees a code. With the sender match above, a code goes only to the site that sent it, or to a listed site, and the rate limit caps use. This is the trade the owner asked for, and it is off unless the file exists.

    Tests

    • tests/agent.test.ts: under *, a tab not on the list gets only a matching-sender code. A GitHub code is refused on https://evil.example and filled on https://github.com/login when github.com is not listed. A listed tab still gets the newest code. Base-domain cases: co.uk, subdomains.
    • A new test for config parsing (valid, wrong types, extra keys, empty list).
    • native/test-host.py: getConfig returns null with no file, the object with a valid file, and null with a broken file.
  4. MehdiMamas commented on Nov 16, 2026

    @MehdiMamas
    OwnerAuthor

    Review of plan 2: not built as written

    A fresh review found real holes, so nothing from plan 2 is built yet.

    1. A site list in the file reopens the leak. A local program could list its own site in the file, open that site and ask for a fill. The page would then read a real code from another sender. Fix: the sender match applies to every tab, listed or not, or the file carries only agentSignIn and allowAll.
    2. Cutting the base domain by hand is unsafe. Shared suffixes break it: 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 tldts getDomain(..., {allowPrivateDomains: true})). A sender whose registrable domain is itself a private suffix matches nothing.
    3. The tab can move while fill_code waits. 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.
    4. Filter before picking the newest. Run the sender filter before "newest", in both pending and fill_code, so a newer mail from another domain cannot hide the right code.

    Lesser points:

    • Parse the address inside the last <...>, not the first @: a display name can contain a fake address.
    • Normalise IDN names.
    • Apply the sender match to open_link too.
    • Optionally require dmarc=pass.
    • The Options "off" switch must always work, even when the file is in use.

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions