Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/agent-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,3 +168,5 @@ The reference CLI adds two codes of its own, without an `id`: `no_host`, when it
## Removed

`fill_code` (filling a one-time code the agent supplied) was removed before 1.4.0 and now returns `unknown_op`. `verify_code` is not its return: the agent never sends or receives a code.

A one-day spike on whether a program outside the browser can use Apple's helper, with its findings and a go or no-go for a desktop app, is in [desktop-app-spike.md](desktop-app-spike.md).
114 changes: 114 additions & 0 deletions docs/desktop-app-spike.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Desktop app spike (#330)

Question: can a process outside the browser talk to Apple's helper, and do list-all, edit or delete exist? Findings only; nothing here ships. The throwaway script is `scripts/spike/non-browser-client.ts`. Nothing in this spike ran against Apple's real helper: no real prompt, unlock or sign-in, no real iCloud data.

## Verdicts

| Edge case | Verdict |
|---|---|
| Apple's helper only accepts the extension id's origin | Needs owner. The rule is a host manifest `allowed_origins` list that the browser enforces; whether Apple's helper also checks its caller is not answerable from this repo or the fake. |
| No list-all message exists | Confirmed for everything PassBridge and the pinned client references send: lookup is per site only. Whether the real helper has an undocumented list-all is only answerable on a real helper (owner checklist). |
| A step needs a real Apple prompt | Not run. Listed in the owner checklist at the end. |

## 1. What a non-browser client needs (script output)

The script (`node scripts/spike/non-browser-client.ts`) is a plain Node process. It uses `src/apple/srp.ts` for the pairing maths (it runs under plain Node, no DOM or `chrome` API) and starts `test-harness/fake-apple-helper/host.ts` itself as a child process, which is the part a browser normally does. Output of one run (the code differs each run):

```
1. capabilities (cmd 14, no pairing needed)
-> frame 10 bytes, cmd 14
<- frame 207 bytes, cmd 14
{"secretSessionVersion":1,"canFillOneTimeCodes":true,"supportsSubURLs":true,"scanForOTPURI":true,"canOpenPasswordsAppToNewPasswordSheet":true,"canSaveAccountWithEmptyUserName":true}
2. lookup before pairing (no key yet, so the body is a placeholder): the helper stays silent
-> frame 167 bytes, cmd 4
reply: none (timed out)
3. handshake m0 (helper shows a 6-digit code on screen)
-> frame 1197 bytes, cmd 2
<- frame 1234 bytes, cmd 2
code the helper is showing: 145197
4. wrong code
-> frame 202 bytes, cmd 2
<- frame 130 bytes, cmd 2
reply: {"MSG":3,"ErrCode":1} (the challenge is burned)
5. new handshake, right code (unlock)
-> frame 1197 bytes, cmd 2
<- frame 1234 bytes, cmd 2
-> frame 202 bytes, cmd 2
<- frame 230 bytes, cmd 2
reply: {"MSG":3,"ErrCode":0}, helper.paired = true
6. per-site lookup (cmd 4, ACT 5 with the page hostname)
-> frame 283 bytes, cmd 4
<- frame 610 bytes, cmd 4
{"STATUS":0,"users":["mia@pb-e2e.invalid"]}
-> frame 307 bytes, cmd 4
<- frame 260 bytes, cmd 4
other site: {"STATUS":3}
done: a plain Node process paired and looked up a login through the 4-byte framing.
```

What it proves, and only that: the framing (4-byte little-endian length plus JSON, `test-harness/fake-apple-helper/host.ts:20-35`), the capability call, SRP pairing with the 6-digit code (`src/apple/protocol.ts:345-380` issue, `:381-430` verify), and an encrypted per-site lookup (`src/apple/protocol.ts:454-470`) all work from a process that is not a browser.

What it cannot prove: the fake is an in-process class (`test-harness/fake-apple-helper/helper.ts`, `FakeHelper.connect`); `host.ts` never looks at who started it. So the output says nothing about whether Apple's helper accepts a caller that is not the browser. The pairing code is the helper's own 6-digit PIN used as the SRP password (`src/apple/srp.ts:1`, `:95-112`); no other credential appears in the handshake.

## 2. The extension id and the origin rule

- Apple's helper is a native-messaging host named `com.apple.passwordmanager` (`src/apple/protocol.ts:15`, `:239`). The browser starts it only for the extension ids in the host manifest's `allowed_origins`. On Windows Apple's manifest lists `pejdijmoenmkgeppbflobdenhhabjlaj` and `mfbcdcnpokpoajjciilocoachedjkima` (`docs/windows-findings.md:19-27`), and `native/windows/install.ps1:62-65` writes the same two when it replaces a broken manifest.
- PassBridge's own hosts use the same mechanism with one id: `native/install.sh:73`, `:82`, `:91` and `native/windows/install.ps1:162` (`allowed_origins` is `chrome-extension://<ext id>/`). `native/install.sh` does not write Apple's manifest on macOS; that one is Apple's.
- PassBridge's manifest key forces Apple's extension id, because "macOS only accepts Apple's extension id" (`SETUP.md:3`). That is the repo's own statement that the Mac side is tied to the id; the repo does not say whether the check is the browser's or the helper's.
- The Windows probe ran the helper as "Native-messaging client, origin `chrome-extension://pejdijmoenmkgeppbflobdenhhabjlaj/`" (`docs/windows-findings.md:36`), so the helper is started with the origin as an argument; whether it looks at it is not recorded.
- On Windows this is partly answered already: a probe spawned the real helper from Node, with no browser, through the alias and the package path (`docs/windows-findings.md:32`), got `GET_CAPABILITIES` (cmd 14) back, and its client hello (`m0`) was accepted (`docs/windows-findings.md:54-64`). So on Windows a non-browser process can connect and start a handshake. That probe did not type the code, so pairing and any lookup are still unproven there.
- macOS is the open part: nothing in the repo shows a non-browser process reaching the Mac helper. The fake has no origin check (`host.ts` takes no argument), so it cannot answer it. Verdict: needs owner on macOS (checklist item 1).

## 3. Messages that exist in the protocol

Defined in the pinned client reference, which is a client, not the helper: `vendor/au2001/README.md:1` calls it "the diff baseline for Apple's helper protocol". It shows which messages are defined, not what the real helper accepts or refuses.

| Message | Defined | Sent by PassBridge | Source |
|---|---|---|---|
| `Action.DELETE = 0`, `QueryStatus.FAILED_TO_DELETE = 4` | yes | never | `vendor/au2001/src/utils/enums.ts:35-37`, `:50`; absent from `src/apple/protocol.ts:76` |
| `Action.UPDATE = 1`, `QueryStatus.FAILED_TO_UPDATE = 5` | yes | never (declared at `protocol.ts:76`, no use) | `vendor/au2001/src/utils/enums.ts:38`, `:51` |
| `Action.ADD_NEW = 3` | yes | never (declared at `protocol.ts:76`, no use) | `vendor/au2001/src/utils/enums.ts:40` |
| `Action.GHOST_SEARCH = 5` (login names for a host) | yes | yes, with `URL: hostname` | `src/apple/protocol.ts:462`, `:537`; `vendor/au2001/src/utils/api.ts:274` |
| `Action.SEARCH = 2` (one password) | yes | yes, with `URL` and `USR` | `src/apple/protocol.ts:484`, `:551`; `vendor/au2001/src/utils/api.ts:339` |
| `Action.MAYBE_ADD = 4` (add, Apple shows its own prompt) | yes | yes | `src/apple/protocol.ts:507` |
| list-all | no message, no `Action` | n/a | `vendor/au2001/src/utils/enums.ts:35-43` lists every `Action`; every query carries a hostname (`src/apple/protocol.ts:454-470`, `:472-490`) |

Commands with an encrypted query id are only 4, 5, 16 and 17 (`src/apple/protocol.ts:69-74`). `vendor/open-passwords/src/protocol.js:58` has the same `Action` list as ours (no `DELETE`).

Verdicts: delete is defined by Apple's enum but nothing here has ever sent it, so whether the helper honours it is unknown. Update is defined and never sent, same. List-all has no message at all. Search is per site only.

The agent protocol does not change this: `save` is add-only and answers `exists` rather than overwrite (`docs/agent-protocol.md:68`, `:150`), and a reply never carries a password or code (`docs/agent-protocol.md:5`). The agent reaches Apple only through the browser extension (`native/passbridge-agent.py:2`, `docs/agent-protocol.md:27`, `:42`), so it shows that a browser is needed today, not what Apple's helper needs.

## 4. Prior art (commits pinned)

All three skip Apple's native-messaging helper. They sign in to Apple's services directly and rebuild the keychain on their own machine, so they say nothing about whether a non-browser process can use Apple's helper.

- Sank6/iCloud-Keychain-for-Linux at `412766faef0776ed745ce749bca2d36e448ceb19` (2026-11-09, MIT). Registers the computer as an Apple device through GrandSlam SRP login, joins the keychain trust (Octagon) and decrypts the iCloud Keychain (`RESEARCH.md:4`, `:19-20`). Needs an anisette server (`README.md`, "What you'll need"). Its browser extension talks to its own host `icp`, not Apple's. Proves: a non-browser client is possible by replacing the whole stack, at the cost of Apple-ID password, 2FA and the device passcode (`README.md`, "Sign in"), and an unofficial path with a risk of locking keychain recovery after about 10 wrong passcodes.
- EttienneM/iCloud-Keychain-for-Omarchy at `5563e3e96e20b68e6b25b2ddd6b56eecbf91da23` (2026-08-30). A fork of the same project with Omarchy setup notes (`OMARCHY.md`); same approach, README says it only reads and changes nothing in the account. It has no licence file in its listing.
- dahlia/coffer at `ce7011940101407529122218a62d9afcbe73d7e9` (2026-09-19, GPL-3.0, Rust, GTK 4). Native Linux client; "The initial synchronization implementation is deliberately read-only" (`README.md`, "Safe before complete"); `ROADMAP.md:198` "Keep the entire remote path read-only"; a native messaging host is still an open item (`ROADMAP.md:260-262`). Proves: a Rust client against Apple's servers is being built by someone else and is read-only so far. GPL-3.0 means no code can be copied into this repo's Apache-2.0 code.

Read on 2026-11-14; each repo was reachable and had source.

## 5. Go or no-go: Tauri 2 quick-access app (search, codes, unlock, add)

Verdict: on Windows a browser-free start is shown to work as far as the hello (`docs/windows-findings.md:32`, `:54-64`); on macOS it is unknown. So: no-go for a browser-free Mac app today; go for it only after owner checklist item 1 passes on macOS, and Windows still needs the pairing step (items 2-4) checked. Without item 1, an app has to run beside a browser that has the extension, which is what the extension already is.

Cost per feature, on the protocol as PassBridge uses it (sizes are estimates, not measured):

| Feature | Needs | Cost |
|---|---|---|
| Search by site | per-site `GHOST_SEARCH` (`protocol.ts:454`), each password read still needs approval in Apple's Passwords (Touch ID) (`docs/agent-protocol.md:50`) | small if the extension stays the engine; large if the SRP and crypto in `src/apple/*` move to Rust |
| Codes | cmds 16 and 17 (`protocol.ts:534`, `:549`), or the code reader on a prompt (`docs/agent-protocol.md:78-104`) | small to medium; the reader is already a signed app |
| Unlock | the 6-digit code from Apple's app every time the session is lost (`docs/agent-protocol.md:53`) | small once connected; a person types the code, except that Windows has an opt-in `unlock` agent op that reads and enters it (`docs/agent-protocol.md:105-111`), which is not supported on macOS |
| Add | `MAYBE_ADD` plus Apple's own prompt (`protocol.ts:499-530`) | small; add-only |
| Browse all, edit, delete | no list-all message; update and delete never sent | not available; not in scope |

Signing and installers (Developer ID and notarization on Mac, a certificate on Windows) are a cost on top, as the issue research notes.

## Owner-only checklist (needs a real Apple helper, real prompts)

1. Start Apple's real helper from a process that is not a browser (macOS: the helper app's binary; Windows: `iCloudPasswordsExtensionHelper.exe` through the WindowsApps alias), pass it the origin argument the browser would, and send cmd 14 (`GET_CAPABILITIES`). Record: replies, or refuses, or exits. Repeat with no origin or a different one. This decides edge case 1.
2. If item 1 connects: run the handshake from `scripts/spike/non-browser-client.ts` against it. This shows the 6-digit code on screen (a real prompt). Record whether pairing succeeds and whether the code is needed every time.
3. If item 2 pairs: send `Action.UPDATE` and `Action.DELETE` for a throwaway test login you create for the purpose, and record the `STATUS`. Never against a real login.
4. If item 2 pairs: send a `GHOST_SEARCH` with an empty URL and with `*`, record whether any list-all comes back.
5. Record the helper and OS versions beside each result.
133 changes: 133 additions & 0 deletions scripts/spike/non-browser-client.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
// Throwaway spike for #330, not shipped (the build copies only the files it lists into dist/).
// A plain Node process, no browser, talks to the fake Apple helper the way the extension does:
// capabilities, SRP pairing with the 6-digit code (src/apple/srp.ts), then a per-site lookup.
// The helper side is test-harness/fake-apple-helper/host.ts, started as a child process, so the
// 4-byte length-prefixed stdio framing is real. The fake never checks who started it (no origin check).
// Run: node scripts/spike/non-browser-client.ts

import { spawn } from "node:child_process";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { FakeHelper } from "../../test-harness/fake-apple-helper/helper.ts";
import { serveHelper } from "../../test-harness/fake-apple-helper/serve.ts";
import { SRPSession } from "../../src/apple/srp.ts";
import { base64ToBytes, bytesToBase64, bytesToBigInt, bytesToUtf8 } from "../../src/apple/crypto.ts";

const b64json = (o: unknown) => bytesToBase64(new TextEncoder().encode(JSON.stringify(o)));
const unb64json = (s: string) => JSON.parse(bytesToUtf8(base64ToBytes(s)));
const log = (s: string) => console.log(s);

const helper = new FakeHelper({ style: "mac" });
const sock = join(tmpdir(), `pb-spike-${process.pid}.sock`);
const served = await serveHelper(helper, sock);

// the "native host": what a browser would start. We start it ourselves, which is the whole point.
const host = spawn(process.execPath, [new URL("../../test-harness/fake-apple-helper/host.ts", import.meta.url).pathname], {
env: { ...process.env, PB_FAKE_HELPER_SOCK: sock },
stdio: ["pipe", "pipe", "inherit"],
});

let inbox = Buffer.alloc(0);
const waiting: Array<(m: any) => void> = [];
host.stdout.on("data", (chunk: Buffer) => {
inbox = Buffer.concat([inbox, chunk]);
while (inbox.length >= 4 && inbox.length >= 4 + inbox.readUInt32LE(0)) {
const n = inbox.readUInt32LE(0);
const msg = JSON.parse(inbox.subarray(4, 4 + n).toString("utf8"));
inbox = inbox.subarray(4 + n);
log(` <- frame ${n} bytes, cmd ${msg.cmd}`);
waiting.shift()?.(msg);
}
});

function send(msg: Record<string, unknown>, wait = true, ms = 1500): Promise<any> {
const body = Buffer.from(JSON.stringify(msg), "utf8");
const head = Buffer.alloc(4);
head.writeUInt32LE(body.length);
log(` -> frame ${body.length} bytes, cmd ${msg.cmd}`);
host.stdin.write(Buffer.concat([head, body]));
if (!wait) return Promise.resolve(undefined);
return new Promise((resolve) => {
const t = setTimeout(() => {
waiting.shift();
resolve(undefined);
}, ms);
waiting.push((m) => {
clearTimeout(t);
resolve(m);
});
});
}

async function handshake(session: SRPSession) {
const r = await send({
cmd: 2,
msg: {
QID: "m0",
PAKE: b64json({ TID: session.username, MSG: 0, A: session.serialize(session.clientPublicKeyBytes), VER: "1.0", PROTO: [1] }),
HSTBRSR: "Chrome",
},
});
const pake = unb64json(r.payload.PAKE);
session.setServerPublicKey(bytesToBigInt(session.deserialize(pake.B)), session.deserialize(pake.s));
}

async function verify(session: SRPSession, pin: string) {
await session.setSharedKey(pin);
const m = await session.computeM();
const r = await send({ cmd: 2, msg: { QID: "m2", PAKE: b64json({ TID: session.username, MSG: 2, M: session.serialize(m, false) }) } });
return unb64json(r.payload.PAKE);
}

async function lookup(session: SRPSession, hostname: string) {
const sdata = session.serialize(await session.encrypt({ ACT: 5, URL: hostname }));
const r = await send({
cmd: 4,
tabId: 0,
frameId: 0,
url: hostname,
payload: { QID: "CmdGetLoginNames4URL", SMSG: JSON.stringify({ TID: session.username, SDATA: sdata }) },
});
if (!r) return undefined;
const smsg = typeof r.payload.SMSG === "string" ? JSON.parse(r.payload.SMSG) : r.payload.SMSG;
return JSON.parse(bytesToUtf8(await session.decrypt(session.deserialize(smsg.SDATA))));
}

try {
log("1. capabilities (cmd 14, no pairing needed)");
const caps = await send({ cmd: 14 });
log(` ${JSON.stringify(caps.capabilities)}`);

const session = new SRPSession(!!caps.capabilities.shouldUseBase64);

log("2. lookup before pairing (no key yet, so the body is a placeholder): the helper stays silent");
const early = await send({ cmd: 4, tabId: 0, frameId: 0, url: "127.0.0.1", payload: { QID: "CmdGetLoginNames4URL", SMSG: JSON.stringify({ TID: session.username, SDATA: "0x00" }) } });
log(` reply: ${early === undefined ? "none (timed out)" : JSON.stringify(early)}`);

log("3. handshake m0 (helper shows a 6-digit code on screen)");
await handshake(session);
log(` code the helper is showing: ${helper.code}`);

log("4. wrong code");
const bad = await verify(session, helper.code === "000000" ? "000001" : "000000");
log(` reply: ${JSON.stringify({ MSG: bad.MSG, ErrCode: bad.ErrCode })} (the challenge is burned)`);

log("5. new handshake, right code (unlock)");
const s2 = new SRPSession(!!caps.capabilities.shouldUseBase64);
await handshake(s2);
const ok = await verify(s2, helper.code);
log(` reply: ${JSON.stringify({ MSG: ok.MSG, ErrCode: ok.ErrCode })}, helper.paired = ${helper.paired}`);

log("6. per-site lookup (cmd 4, ACT 5 with the page hostname)");
const found = await lookup(s2, "127.0.0.1");
log(` ${JSON.stringify({ STATUS: found.STATUS, users: found.Entries?.map((e: any) => e.USR) })}`);
const none = await lookup(s2, "elsewhere.invalid");
log(` other site: ${JSON.stringify({ STATUS: none.STATUS })}`);

if (!ok || found.STATUS !== 0 || none.STATUS !== 3 || !helper.paired) throw new Error("spike check failed");
log("done: a plain Node process paired and looked up a login through the 4-byte framing.");
} finally {
host.stdin.end();
host.kill();
await served.close();
}
Loading