Skip to content

Spike: can a non-browser client reach Apple's helper (#330) - #338

Merged
MehdiMamas merged 4 commits into
mainfrom
desktop-spike-330
Nov 14, 2026
Merged

MehdiMamas merged 4 commits into
mainfrom
desktop-spike-330

Conversation

@MehdiMamas

Copy link
Copy Markdown
Owner

Findings only, nothing shipped. docs/desktop-app-spike.md has the sourced findings, a verdict per edge case, an owner-only checklist and a go or no-go. scripts/spike/non-browser-client.ts is a throwaway script that pairs and looks up a login against the fake helper (node scripts/spike/non-browser-client.ts).

Refs #330

Before: nothing showed what a process outside the browser needs to reach Apple's helper protocol.
Now: scripts/spike/non-browser-client.ts pairs and looks up a login over the 4-byte framing against the fake helper.
Before: no written answer on whether a non-browser client can reach Apple's helper.
Now: docs/desktop-app-spike.md has sourced findings, script output, verdicts, an owner checklist and a go or no-go; linked from docs/agent-protocol.md.
Before: four citations pointed a few lines off.
Now: they point at the lines they name.
@MehdiMamas MehdiMamas linked an issue Nov 14, 2026 that may be closed by this pull request
@MehdiMamas

Copy link
Copy Markdown
Owner Author

Check for PR #338

  • 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:9 (verdict: needs owner; the fake has no origin check, :59; owner step 1 in the checklist from :106)
  • pass: given no list-all message exists -> expect search is per-site only and the findings say so — docs/desktop-app-spike.md:10 (table in section 3, from vendor/au2001/src/utils/enums.ts:35-43)
  • pass: given a step needs a real Apple prompt -> expect it is listed for the owner, not run — docs/desktop-app-spike.md:11 (checklist from :106)

The script output is quoted in section 1 of the doc. Typecheck and test pass locally and CI is green.

@MehdiMamas

Copy link
Copy Markdown
Owner Author

Diff review: PR #338 (head c563647), checked against the Plan, its amendment, the Plan review and the Check comment on #330. Read only.

Protocol claims, spot-checked against src/apple/protocol.ts and vendor/au2001 (all hold):

  • Action list and "UPDATE never used": src/apple/protocol.ts:76; uses at :462, :484, :507, :537, :551. Encrypted query ids only 4, 5, 16, 17: :69-74. Per-host lookup: :454-470, :472-490. Issue/verify: :345, :381. Host name: :15, :239.
  • DELETE and FAILED_TO_DELETE: vendor/au2001/src/utils/enums.ts:35-43 (DELETE = 0), :50. No list-all Action. api.ts:274 and :339 match. vendor/au2001/README.md:1-3 says "diff baseline", and the doc words it as "defined", not "accepted by the helper" (Plan review 2 is met). vendor/open-passwords/src/protocol.js:58 has the same Action list as ours (no DELETE).
  • Origin rule: native/install.sh:73, :82, :91, native/windows/install.ps1:62-65 and :162, docs/windows-findings.md:19-27, SETUP.md:3 all say what the doc says. Fake has no origin check: test-harness/fake-apple-helper/host.ts:1-37.
  • Agent protocol cites (docs/agent-protocol.md:5, :27, :42, :53, :68, :150) and native/passbridge-agent.py:2 match.
  • External repos are pinned and exist at those commits and dates: Sank6 412766f (2026-11-09, MIT), Omarchy 5563e3e (2026-08-30, no licence), coffer ce70119 (2026-09-19, GPL-3.0). I spot-checked the quoted README, RESEARCH.md and ROADMAP.md lines (Anisette, the ~10 wrong passcodes warning, "deliberately read-only", ROADMAP.md:198 and :260-262).

Script safety:

  • scripts/spike/non-browser-client.ts only starts a FakeHelper, serves it on a socket under tmpdir (pb-spike-.sock) and spawns test-harness/fake-apple-helper/host.ts. It does not touch Apple's helper, a real prompt or a real vault. The socket is closed in finally.
  • It reuses src/apple/srp.ts, as the amendment said. CI is green, including check and run-all.
  • Not shipped: scripts/build.ts:11 and :24 copy only a listed set of items and files into dist/, and nothing under scripts/ is in the list. The script is typechecked through tsconfig.tools.json (scripts/**/*.ts), which is what the amendment asked for.

Sensitive data: no local paths, personal data or mention of AI, agents-as-tools or assistants in the three changed files. The only login is the fake mia@pb-e2e.invalid. "agent" appears only as the PassBridge agent feature.

Deviations:

  1. docs/desktop-app-spike.md section 2 (the :74 line about the Windows probe) quotes docs/windows-findings.md:36 but leaves out :32 and :54-64. Those lines say Node spawned the real Windows helper, cmd 14 returned capabilities, and an m0 client hello was accepted with no browser involved. That is real evidence on the central question. It is not proof of the origin rule, because :36 shows an origin was passed. The verdict "needs owner" is still defensible. But the doc and the go or no-go say a non-browser client is untested, and they should cite that prior evidence for Windows and say the macOS side is the open part.
  2. Minor: the table in section 3 omits Action.ADD_NEW = 3, though it says "lists every Action". docs/desktop-app-spike.md:98 says "Touch ID or Windows Hello" for docs/agent-protocol.md:50, which only says Touch ID. The "Unlock ... never silent on macOS" line does not mention the Windows unlock op (docs/agent-protocol.md:67).

Everything else in the Plan and its amendment is met: Action.DELETE and FAILED_TO_DELETE are checked, a one-line verdict is given per edge case, the owner steps are a checklist, pins are present, the link is in docs/agent-protocol.md, and the script output is quoted.

OK to merge: yes, after fixing deviation 1 in the doc (a wording change; none of the doc's claims are wrong). Item 2 can be fixed in the same edit.

Before: the origin finding ignored the Windows probe, ADD_NEW was missing, and two cells misquoted their sources.
Now: Windows hello is cited, macOS is named as the open part, and the table and cells match their sources.
@MehdiMamas

Copy link
Copy Markdown
Owner Author

Check for PR #338 (after the review fixes, commit 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:9 (Windows: connects and accepts the hello, docs/windows-findings.md:32, :54-64; macOS is the open part, owner step 1 in the checklist)
  • pass: given no list-all message exists -> expect search is per-site only and the findings say so — docs/desktop-app-spike.md:10 (Action table in section 3, now with ADD_NEW, from vendor/au2001/src/utils/enums.ts:35-43)
  • pass: given a step needs a real Apple prompt -> expect it is listed for the owner, not run — docs/desktop-app-spike.md:11 (owner checklist at the end)

CI is green on 4b72323.

@MehdiMamas

Copy link
Copy Markdown
Owner Author

Check: PR #338 at head 4b72323, against the Plan edge cases (#330 (comment))

  • pass: plain Node client pairs and looks up a login through the 4-byte framing (script run, exit 0, "done" line printed)
  • pass: lookup for another site returns STATUS 3, no user list
  • pass: no browser process involved
  • pass: diff is docs, one script and one link; dist, extension and helper untouched
  • pass: real Apple helper not run; listed as owner-only step 1 in docs/desktop-app-spike.md

@MehdiMamas

Copy link
Copy Markdown
Owner Author

Check: PR #338 at head 4b72323, one line per Plan edge case

  • 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:60 (Windows shown to work, macOS needs owner, checklist item 1)
  • pass: given no list-all message exists -> expect search is per-site only and the findings say so — docs/desktop-app-spike.md:78
  • pass: given a step needs a real Apple prompt -> expect it is listed for the owner, not run — docs/desktop-app-spike.md:108

@MehdiMamas

Copy link
Copy Markdown
Owner Author

Diff review: PR #338 (head 4b72323). Read only. I spot-checked the doc's cites against the head. protocol.ts:69-76, enums.ts:35-52, agent-protocol.md:50 and :105-111, and windows-findings.md:32 all say what the doc says. The script only uses the fake helper. I found no correctness, security or cost problems. Two minor points:

  1. scripts/spike/non-browser-client.ts, the final check (if (!ok || found.STATUS !== 0 ...)). !ok can never be true, because verify always returns an object. A wrong code at step 5 would not fail the check. It would only fail at helper.paired. Use ok.ErrCode !== 0 instead.
  2. The fake helper (and so the script) never sees an origin. That is stated in the doc at :59, so the script's claims are limited as the doc says. I found no overclaim.

Nothing blocks merge.

@MehdiMamas
MehdiMamas merged commit 0b75d07 into main Nov 14, 2026
5 checks passed
@MehdiMamas
MehdiMamas deleted the desktop-spike-330 branch November 14, 2026 18:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

PassBridge desktop app (Rust): replace the Passwords app

1 participant