Skip to content

PassBridge desktop app (Rust): replace the Passwords app #330

Closed

Description

@MehdiMamas

Goal

A Rust-based PassBridge desktop app (Mac + Windows) so the Passwords app is never needed: browse/search/edit logins, codes, unlock, settings, with the extension's UI.

Today

Only the Chrome extension plus native helper agent (native/, src/). No desktop UI.

Plan (research first, no build before the owner decides)

  • Research with sources: Tauri vs other Rust/web options, and an existing maintained tool that already fits. Weigh cost, developer support, simplicity.
  • Scope, machines, how the app talks to the agent and store.
  • Then one lettered decision for the owner, recommended first, with an Alternatives section.

Risks

Apple's protocol exposes limited write ops; unlock needs the Apple pairing code (see #328).

Activity

  1. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Research: desktop app options for #330 (fetched 2026-11-14; no code written, nothing built)

    Short answer: the blocker is not the GUI framework, it is Apple's protocol. As PassBridge uses it today it can look up logins for one site, not list the whole vault, and it has no delete. A "replace the Passwords app" app cannot be built on that. A small quick-access app can.

    1. What the protocol allows (repo, file:line)

    • Commands PassBridge speaks: GET_LOGIN_NAMES_FOR_URL (4), GET_PASSWORD_FOR_LOGIN_NAME (5), SET_PASSWORD_FOR_LOGIN_NAME_URL (6), NEW_ACCOUNT_FOR_URL (7), GET_ONE_TIME_CODES (16), LAUNCH_PASSWORDS_APP (13): src/apple/protocol.ts:49-66. Only 4, 5, 16, 17 have encrypted query ids (protocol.ts:69-74).
    • Search is per site, not per vault: login-name and GHOST_SEARCH queries take a hostname (protocol.ts:456-478). No "list all logins" command is used anywhere in the repo.
    • Add only: Action.MAYBE_ADD plus Apple's native confirmation prompt (protocol.ts:505-530). Action.UPDATE exists as a constant (protocol.ts:76) but nothing in the repo sends it. No delete exists. The agent save op is add-only, exists if the username is there (docs/agent-protocol.md:67, :139).
    • Unlock/pairing is the 6-digit code from Apple's app (docs/agent-protocol.md:53, :64-65). Every password read still needs Apple's approval (Touch ID) (docs/agent-protocol.md:51).
    • Codes: verify_code presses Allow on Apple's prompt and reads the digits, Mac and Windows (docs/agent-protocol.md:77-96). TOTP read is cmd 16/17.
    • How an app would talk to us: the helper agent relays one JSON request per line over a Unix socket (Mac) or a named pipe plus agent.key (Windows) (native/passbridge-agent.py:91-125, docs/agent-protocol.md:23-34). The relay forwards to the browser extension, which holds the Apple session and does the crypto (src/apple/srp.ts, crypto.ts). So today the app would need a browser running with the extension. Replies never contain a password or code (docs/agent-protocol.md:5), so the agent API cannot feed a viewer UI.
    • Not verified: whether Apple's native helper accepts any caller other than a browser extension id. This one experiment decides if a browser-free app is possible.

    2. Is something already made?

    Tool What it does Fit Source
    bendews/apw Mac CLI: list per domain, save/update, OTP get; no delete; needs a Chromium browser plus the iCloud Passwords extension; 270 stars Same limits as ours, Mac only, CLI; a menubar app is only listed as future work github.com/bendews/apw (2026-11-14)
    apwcli / apwlib (PyPI) Python CLI and library, Mac only, same approach Not a UI search 2026-11-14 (page did not load; listing text only)
    au2001/icloud-passwords-firefox Firefox extension Not a desktop app TidBITS 2024-12-06
    Bitwarden, KeePassXC, Proton Pass Full managers with their own vault Replace iCloud instead of fronting it; owner rejected other apps for passkeys (#197) search result

    No maintained desktop client for iCloud Passwords with browse/edit turned up. Nothing to build on except our own relay. This is one search per topic, so a missed project is possible.

    3. Framework options (UI)

    Option Dev pool Size / cost Signing Notes
    Tauri 2 (Rust core, system webview) 112.9k GitHub stars, Apache-2.0 and MIT (github.com/tauri-apps/tauri) Blogs claim 8-15 MB vs 80-244 MB for Electron; unverified (openreplay). Free. Mac: Developer ID + notarization, needs the $99/yr program (Tauri docs); already paid. Windows: OV/EV cert or Azure Artifact Signing; SmartScreen can warn on new releases either way (Tauri docs) Reuses src/ui as front end. The Python helper can ship as a sidecar (externalBin, one binary per target) (docs). Backend needs Rust.
    Electron Largest pool Bundles Chromium; biggest Same Apple program; Azure Artifact Signing "cheapest" on Windows (Electron docs) Easiest web UI reuse, no Rust. Heavy for a tray tool.
    Swift (Mac) + WinUI (Windows) Two small pools Smallest, two codebases Same Doubles the work; owner asked for Rust and the extension UI.
    egui / Slint / Dioxus Small pools Slint: GPL, royalty-free or paid licence, prices not shown (slint.dev); no good source found for egui and Dioxus Same UI is rewritten, the extension UI is not reused.

    Alternatives (arguing against Tauri first)

    • Rust buys little here. The hard part (Apple session, SRP, encryption) lives in the extension's TypeScript. A "Rust core" means porting src/apple/* to Rust: a rewrite with no user-visible gain and a new place for crypto bugs. Keeping the TS inside a webview avoids it.
    • The extension already is a window. A side panel with search, codes and unlock gives the same UI with no signing, installer or second update channel.
    • Replace-all is blocked by the protocol, not by us. No list-all, no delete, edit only through Apple's prompt. No framework changes that.
    • Mac notarization and Windows SmartScreen are ongoing friction that today's unpacked extension install avoids.

    Scope (what could ship, in order)

    1. Search by site or URL (not a vault list): usernames, with Touch ID per password.
    2. Codes (TOTP, plus the existing Apple prompt reader).
    3. Unlock and pairing (pair_start/pair_pin), settings (reuse Options).
    4. Add login (add-only, Apple prompt). Edit only if Action.UPDATE is proven to work (unverified). Delete: not possible.

    Machines

    Mac and Windows (same as the helper, docs/agent-protocol.md:9). Each OS builds and signs on its own; Windows needs the desktop PC to test iCloud for Windows and SmartScreen.

    Risks

    • Browse-all and delete are not possible with today's protocol, so promise less than "replace the Passwords app".
    • Unverified: whether Apple's helper talks to a non-browser caller; if not, the app depends on a running browser plus the extension.
    • A viewer that shows passwords would break the "no password or code in an agent reply" rule; passwords stay in the extension.
    • Unlock needs Apple's pairing code whenever the session is lost (Live demo readiness: fill, auto-unlock when locked, code reader on Mac, desktop and laptop #328).
    • Size and speed figures are blog claims, not measured.

    Options

    A) Spike only (recommended): about a day, no app. Test whether a non-browser process can talk to Apple's helper, and whether Action.UPDATE or any list-all query works. The result decides B or C. No cost beyond time.
    B) Tauri 2 app, if the spike passes: reuse src/ui, keep or port the protocol, ship search, codes, unlock, add. Uses the existing $99 Apple program for signing; Windows cert is a new decision.
    C) No app: grow the extension (side panel with search, codes, unlock) and drop the "replace the app" goal. Cheapest, no signing, same UI.
    D) Electron or a pure-Rust UI: not recommended (heavier, or the UI is rewritten).

  2. mahelbir commented on Nov 14, 2026

    @mahelbir
    Contributor

    iCloud for Windows (Passwords) is really terrible, both in terms of its GUI and its synchronization. It would be great if we could add a GUI to replace it. A CLI that can communicate using the same protocol as the Bitwarden interface, or the macOS Passwords interface itself, might be a good idea. If necessary, I already have an Apple Developer account for signing.

    Some resources:

  3. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Plan: one-day spike, no app yet (decision A).

    Question: can a process outside the browser talk to Apple's helper, and do list-all, edit or delete exist?
    Files: new docs/desktop-app-spike.md (findings only); a throwaway script under scripts/spike/ (not shipped); reads src/apple/protocol.ts (lines 76, 456-478), native/passbridge-agent-cli.py and docs/agent-protocol.md.
    Steps:

    1. From a plain Node process (no browser), speak the native-messaging protocol to test-harness/fake-apple-helper: handshake, per-site lookup, unlock. Shows what a non-browser client needs (extension id, pairing, framing).
    2. Read Apple's helper side for any list-all, update or delete message, using the pinned upstream code in vendor/ and the repo's protocol notes; record what exists and what is never sent.
    3. Prior art from the suggestion above: read https://github.com/Sank6/iCloud-Keychain-for-Linux, https://github.com/EttienneM/iCloud-Keychain-for-Omarchy and https://github.com/dahlia/coffer and note what each proves about a non-browser client.
    4. Real helper: no real Apple prompt or unlock is run in the spike; anything needing one is listed as a step for the owner.
    5. Write the findings and a go or no-go for a Tauri 2 quick-access app (search, codes, unlock, add), with the cost of each feature.
      Edge cases:
    • given Apple's helper only accepts the extension id's origin -> expect the spike states whether a non-browser client can connect at all
    • given no list-all message exists -> expect search is per-site only and the findings say so
    • given a step needs a real Apple prompt -> expect it is listed for the owner, not run
      Tests: the spike script runs against the fake helper (node scripts/spike/.ts) and its output is quoted in the doc.
      Done when: docs/desktop-app-spike.md is in a PR with sourced findings and a go or no-go.
  4. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Plan review

    1. Step 2 and the "never sent" claim miss a delete action. vendor/au2001/src/utils/enums.ts (enum Action) has DELETE = 0 and QueryStatus has FAILED_TO_DELETE = 4. src/apple/protocol.ts:76 has no DELETE at all. The research said "no delete exists", but the vendored enum shows Apple's side defines one. The plan should name DELETE as something to check, not only list-all and UPDATE. Action.UPDATE is only declared at src/apple/protocol.ts:76 and never used. That claim holds. The uses are at :462, :484, :507, :537, :551 (GHOST_SEARCH, SEARCH, MAYBE_ADD). The per-host query at :456-478 also matches.

    2. Step 2 says "Apple's helper side ... using the pinned upstream code in vendor/". vendor/au2001 is a client-side reference (vendor/au2001/README.md: "diff baseline for Apple's helper protocol"). It is not the helper. It can show which messages exist (enums.ts), but not what the helper accepts or refuses. Reword the step so the finding is "defined in the protocol" and not "supported by the helper". The real helper check is already in step 4 for the owner.

    3. Step 1 cannot answer "what a non-browser client needs (extension id, ...)". test-harness/fake-apple-helper/helper.ts is an in-process class (FakeHelper.connect). serve.ts puts it on a Unix socket as newline JSON. host.ts is the only part with the 4-byte stdio framing, and it never checks an origin. A script that uses FakeHelper or serve.ts skips framing and any origin check, so the first edge case (helper only accepts the extension id's origin) cannot be shown by the fake. The origin rule lives in the host manifest (native/install.sh:73, :82, :91 allowed_origins, and the Windows install.ps1) and is enforced by the browser. native/install.sh and native/windows/install.ps1 should be listed under Files and read. The plan should say plainly that the fake proves framing and SRP only, and that the origin question stays open for the owner.

    4. Step 1 "unlock" needs SRP with a 6-digit code. The plan does not say whether the script reuses src/apple/srp.ts and crypto.ts (which may need chrome or DOM APIs) or test-harness/automation/srp-reference.ts. Name the choice, since it decides if the script runs under plain node.

    5. Test command: node scripts/spike/<name>.ts is runnable (package.json engines node >=22.18, "test": "node scripts/test.ts", "type": "module"). Give the real file name and note that relative imports need the .ts extension. scripts/** is in tsconfig.tools.json, so the throwaway script is typechecked by pnpm typecheck. Either make it pass or exclude it, and check that build.ts and the release zip skip scripts/spike ("not shipped" is not checked anywhere).

    6. Done-when is only partly checkable. "Sourced findings" and "go or no-go" have no bar. Suggest: each finding cites file:line or a URL, the script output is quoted, and the three edge cases each get a one-line verdict (can connect / cannot / needs owner).

    7. Step 3 reads three external repos but sets no way to cite them (commit hash and date), and the plan does not say what to do if one is gone or has no source. Add "pin the commit read".

    8. Missed: the doc is not linked from README or docs/agent-protocol.md, and the owner steps from step 4 should be a checklist at the end of the doc. native/passbridge-agent-cli.py and docs/agent-protocol.md describe the relay to the browser, not Apple's helper. They support the "needs a browser today" point only.

    Files: all named paths exist at origin/main, and the new ones (docs/desktop-app-spike.md, scripts/spike/) are marked new.

  5. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Plan amendment (after Plan review):

    Files added: native/install.sh (allowed_origins at lines 73, 82, 91) and native/windows/install.ps1 (the extension-id rule), scripts/spike/non-browser-client.ts (script name), a link to the doc from docs/agent-protocol.md.
    Steps changed:

    • Step 2 also checks Action.DELETE and QueryStatus.FAILED_TO_DELETE in vendor/au2001/src/utils/enums.ts; vendor/ is a client reference, so it shows which messages are defined, not what Apple's helper accepts: the findings say so and list what only a real helper can answer.
    • The fake helper has no origin check (FakeHelper is in-process, stdio framing is only in host.ts), so the extension-id question is answered from native/install.sh allowed_origins and the install scripts, not from the fake.
    • The script reuses src/apple/srp.ts for unlock and stays out of the release build and typecheck-clean under tsconfig.tools.json.
    • Each external repo is pinned to a commit hash when cited.
      Done when (stronger): docs/desktop-app-spike.md in a PR with every finding citing file:line or a URL, the script output quoted, a one-line verdict per edge case, the owner-only steps as a checklist, and a go or no-go.
  6. added a commit that references this issue on Nov 14, 2026
  7. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Late step: the Plan amendment (comment 6881653082) listed added files and steps but repeated no Edge cases or tests section; it relies on the Plan's own, which stand unchanged:
    Edge cases:

    • given Apple's helper only accepts the extension id's origin -> expect the spike states whether a non-browser client can connect at all
    • given no list-all message exists -> expect search is per-site only and the findings say so
    • given a step needs a real Apple prompt -> expect it is listed for the owner, not run
      Tests: node scripts/spike/non-browser-client.ts against the fake helper, pnpm typecheck, pnpm test. Done after the code, posted after the last commit.
  8. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Check: PR 338 at head 4b72323.

    • pass: given Apple's helper only accepts the extension id's origin -> expect the spike states whether a non-browser client can connect at all — docs/desktop-app-spike.md (origin rule finding, cites docs/windows-findings.md:32 and :54-64; macOS marked open)
    • pass: given no list-all message exists -> expect search is per-site only and the findings say so — docs/desktop-app-spike.md (messages table; src/apple/protocol.ts:456-478)
    • pass: given a step needs a real Apple prompt -> expect it is listed for the owner, not run — docs/desktop-app-spike.md (owner checklist); scripts/spike/non-browser-client.ts runs only against the fake helper
  9. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Plan: tests and edge cases for the spike (written after the code; run and passed on head 4b72323)

    Tests to run:

    • node scripts/spike/non-browser-client.ts exits 0 and prints the done line.
    • pnpm typecheck and pnpm test stay green in CI (5 of 5 checks passed).

    Edge cases:

    • given the fake helper and a paired plain Node client -> expect a login lookup for the allowed site to return the user list
    • given a lookup for a site that was not allowed -> expect STATUS 3 and no user list
    • given no browser process -> expect the 4-byte framed messages still round-trip
    • given a PR that only adds docs, one script and a link -> expect no change to dist, the extension or the helper
    • given the real Apple helper on macOS -> expect nothing run here; the doc lists it as an owner-only step 1
  10. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Research update after @mahelbir's comment (repos fetched 2026-11-14, all public):

    Project What it does Fit
    Sank6/iCloud-Keychain-for-Linux @412766f, MIT, Python, 83 stars Registers the computer as an Apple device (Apple ID sign-in, anisette data, iCloud Security Code / escrow), downloads the keychain into a local encrypted store, a browser extension fills it Works with no Apple app at all, so it is the only route for Linux. Needs an anisette server; untested with Advanced Data Protection; a wrong passcode about 10 times locks keychain recovery for good
    EttienneM/iCloud-Keychain-for-Omarchy @5563e3e, fork of the one above Omarchy install guide Same approach and risks
    dahlia/coffer @ce70119, GPL-3.0, Rust, GTK 4 Native Linux client; local anisette, reads and decrypts keychain records from CloudKit, read-only for now, early development Closest to a Rust desktop app; GPL-3.0 means we can study it but not copy it into this code base without a licence decision

    Alternatives for #330, with the spike result (docs/desktop-app-spike.md):

    • A. No app yet: owner step 1 on a real Mac first (start Apple's helper from a non-browser process). On Windows a browser-free start already works as far as the hello.
    • B. Desktop app (Tauri) on top of Apple's own helper, only after step 1 passes. Cheapest route, same protocol the extension already uses; Mac and Windows only.
    • C. Own Apple-device registration like the three projects above: the only way to Linux, but it uses reverse-engineered sign-in and keychain protocols that can lock a real account's recovery, so it needs its own plan and a test account.
    • D. A command-line tool or local server that speaks the Bitwarden client protocol (idea from @mahelbir), so existing Bitwarden clients can read the Apple vault. It would sit on top of B or C, so it is a later phase, not a replacement.

    Thanks @mahelbir for the idea, the pointers and the signing offer. A pull request for any part of this is welcome.

  11. MehdiMamas commented on Nov 14, 2026

    @MehdiMamas
    OwnerAuthor

    Thanks @mahelbir, this is really useful. I looked at the three projects you linked and wrote up what each does, how it fits, and four ways forward above. A command-line tool or local server that speaks the Bitwarden protocol is on the list as a later step on top of the main work. Your offer of an Apple Developer account for signing is noted and I may take you up on it. If you want to try any part of this yourself, a pull request is very welcome.

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

    ideaFeature ideastartedWork in progress

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions