Skip to content

feat(browser): hand off passkey sign-in to the system browser - #64498

Open
wra-sol wants to merge 6 commits into
anomalyco:devfrom
wra-sol:passkey-handoff
Open

wra-sol wants to merge 6 commits into
anomalyco:devfrom
wra-sol:passkey-handoff

Conversation

@wra-sol

@wra-sol wra-sol commented Nov 17, 2026 •

Copy link
Copy Markdown

Issue for this PR

Refs #60191 — the passkey/security-key hang this turns into an explicit, consented handoff. #63002 takes the wider signed-in-pane direction; how this fits alongside it is covered in the review reply.

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

Sign-in that needs a passkey, security key, or SSO hangs in the in-app browser (#60191): GitHub sudo mode's "Use passkey", Cloudflare → Google SSO. The pane has no platform authenticator — Electron services none until configureWebAuthn(), its Touch ID path makes app-scoped credentials in a per-attachment partition, and using existing iCloud Keychain passkeys needs associated domains or Apple's managed web-browser entitlement, which OpenCode can't hold. Evidence and rejected alternatives: packages/plugin-browser/docs/passkeys.md.

browser.handoff({ tabID }) is the escape hatch. Nothing opens on the agent's word: the pane shows a banner with the page's URL and an Open button, and shell.openExternal fires only on that click. The banner then waits for Done or Cancel (10 minutes; the server's backstop is 12) and the tool resolves { state: "completed" | "cancelled" | "timedOut", host }. The pane stays signed out on purpose — inheriting the session would mean copying its cookies. Work that needs the sign-in stays with the user in the system browser.

Manual checks (both need a real credential step):

  1. github.com/settings/tokens → Generate new token (classic) → sudo mode → Use passkey: the handoff opens the page in the default browser after the user clicks Open; Done resolves { state: "completed", host: "github.com" } and the pane stays signed out.
  2. dash.cloudflare.com → Google SSO → passkey/security-key step: same flow.

How did you verify your code works?

packages/gui-plugins/src/browser/handoff.test.ts — nothing opens before the user's Open; one launch even on a double click; Done/Cancel/timeout/abort/tab-close/binding-close each settle exactly once; non-web and credential-bearing URLs are refused; results are { state, host } only; launch errors never echo the URL. connection.test.ts — the banner's answers reach main with { binding, id, action }. plugin-browser/test/rpc.test.ts — the output schema and the search terms. A banner story in packages/app/component-tests/browser-pane.spec.ts walks pending → Open → opened → Done → completed through the real model. bun run check passes repo-wide. The two tunnel.test.ts failures on my machine also fail on pristine dev (local TCP/proxy environment).

Screenshots / recordings

Before, asking (nothing has opened yet), opened, finished:

Before Asking
before pending
Opened Finished
opened completed

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Added by the opencode bot (AI-generated).

Related: #60191

Public API: adds the browser.handoff tool operation, a BrowserPane handoff IPC method and a handoff pane event (backwards compatible)

The in-app browser has no platform authenticator: Electron services no
WebAuthn platform request until configureWebAuthn, its Touch ID path
creates app-scoped credentials in an ephemeral partition, and Apple's
generic passkey path needs entitlements (associated domains or the
managed web-browser public-key-credential entitlement) OpenCode cannot
hold. A login that needs a passkey, security key, or SSO therefore
cannot complete in the pane.

browser.handoff({ tabID }) opens the tab's page in the user's default
browser and waits for Done or Cancel in a Review-pane banner, resolving
{ state, host } only. The pane stays signed out by design: no cookie or
credential crosses in either direction, the URL is used once and never
returned or echoed in errors.

The finding, rejected alternatives, and invariants are recorded in
packages/plugin-browser/docs/passkeys.md. No feature flag: the action is
additive inside the attachment-gated browser plugin, like preview.
@github-actions github-actions Bot added the needs:compliance This means the issue will auto-close after 2 hours. label Nov 17, 2026

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I couldn't run this: it needs the Electron desktop app (shell.openExternal and the pane). The new unit tests pass (handoff.test.ts, connection.test.ts and rpc.test.ts), and plugin-browser and gui-plugins type-check clean with tsc. The settling logic looks sound: Done, Cancel, the timeout, abort, closing the tab, closing the binding and dispose all end the handoff once, and the URL never appears in events, results or errors.

Public API: adds the browser.handoff({ tabID }) tool operation (output { state: "completed" | "cancelled" | "timedOut", host }), the handoff IPC method on BrowserPane, and a handoff pane event. Nothing existing changes. An older desktop answers unsupported, so it is backwards compatible.

Concerns:

  • The agent can open the user's real browser without the user's consent. Until now the agent was confined to the sandboxed pane. With this tool it can navigate a tab anywhere over http(s) and then open that page in the user's default, signed-in browser; the banner only appears afterwards. That covers phishing pages from a misled agent and GET requests that change state on sites the user is logged into. Please have the user confirm before openExternal, for example by showing the banner first with an Open button (inline comment).
  • The tool description tells the agent to "continue in the pane" after the handoff, but the pane stays signed out by design. An agent that follows it will hit the same sign-in again and may loop (inline comment). The skill text has this right.
  • Value to the agent: since the pane never gets the session, completed gives the agent nothing to act on. The tool is close to the existing Open in system browser button plus a wait that blocks the agent for up to 10 minutes. Maintainers may want to decide whether an agent-facing tool is needed or a pane notice is enough. #63002 handles passkeys differently (a notice plus importing cookies from the user's browser), so the direction should be settled first.

Related: #60191

// The launch happens before the banner: a browser that never opened is a tool error, not a confirmation the user
// never saw. Electron's rejection can name the URL, so the error the agent reads is this one instead.
try {
await input.openExternal(url.href)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This opens the user's default (signed-in) browser at whatever http(s) page the agent's tab is on, before the user has agreed to anything; the Done/Cancel banner only appears afterwards. Until now the agent stayed inside the sandboxed pane, and this lets it trigger navigations, including state-changing GETs, in the user's real browser profile. Could the pending banner come first, with an Open button the user presses, and openExternal run only from that click?

Comment thread packages/plugin-browser/src/rpc.ts Outdated
),
operation(
"handoff",
"Move this tab's current page to the user's system browser when a login needs a passkey, security key, WebAuthn authenticator, or single sign-on (SSO) the in-app browser cannot service. Opens the page in the default browser and waits for the user to choose Done or Cancel in the Review pane. The pane never receives that session, its cookies, or its credentials and stays signed out; do not ask the user to paste, read, or repeat them. Use it for the credential step, then continue in the pane.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Use it for the credential step, then continue in the pane." contradicts the design: the pane stays signed out, so an agent that follows this will hit the same login wall again and may call handoff repeatedly. The skill text says it correctly ("Work that needs the sign-in stays with the user in the system browser"), and this description should say the same.

Review follow-up: the banner now shows first, with the page's URL, and
shell.openExternal runs only on the user's Open click; a second Open cannot
launch it twice. A launch the user started that fails rejects the waiting
tool call through the normal failure path, and the banner reports it
briefly. The handoff description no longer tells the agent to continue in
the pane, which the signed-out pane cannot do. Docs and the decision record
match the new flow.
@wra-sol

wra-sol commented Nov 17, 2026

Copy link
Copy Markdown
Author

Thanks for the review — all four points taken seriously. 1 and 2 are fixed in the new commit; 3 and 4 are design calls, answered as honestly as I can below.

Consent before launch — agreed, and restructured. begin no longer touches openExternal: the pane emits a pending banner first, carrying the page's URL (the same URL the address bar already shows), with Open and Cancel. The desktop calls shell.openExternal only when the user's Open arrives over the handoff IPC, and a second Open while a launch is in flight is ignored. A launch that fails shows a brief failed banner and rejects the waiting tool call with the plain error, so it travels the normal failure path. The URL still never appears in tool results or errors. handoff.test.ts now leads with "nothing opens until the user's Open".

"Continue in the pane" — you're right; that sentence invited exactly the loop you describe. The description now says the pane stays signed out and work that needs the sign-in stays with the user in the system browser. The skill already said so.

Value to the agent — the honest answer: completed gives the agent no session, by design. What it buys is that the dead-end becomes a taught, reliable move: the skill tells the agent when a login needs a step the pane can't service, the handoff gets the user to the right page with one click, and the agent learns the outcome instead of hammering a step that can never complete (#60191's navigator.credentials.get hangs out its full timeout today). If maintainers feel a pane notice is enough without an agent-facing tool, that's a defensible cut — say so and I'll rework this down to the notice.

#63002 — I read it as complementary rather than competing, but the direction is yours to settle. Its known limits agree with the finding here ("real passkey support on macOS needs a newer Electron and a browser entitlement"), and its fail-fast + notice + per-site import covers the common "I just need to be signed in" case better than this PR ever could. Where import doesn't help is step-up authentication: GitHub's sudo mode re-demands a credential even with valid session cookies, and Google SSO's authenticator step likewise — those still need the user's real browser. On top of #63002 this tool stays useful for exactly that case; if you'd rather tell one browser story, I'm glad to hold this until persisted-browser lands and rebase whatever survives.

#60191 — linked as Refs rather than Fixes, since the in-pane prompt itself remains impossible and the issue may want to stay open for the fail-fast / stop-advertising-unfulfillable-capabilities part.

@github-actions github-actions Bot removed the needs:compliance This means the issue will auto-close after 2 hours. label Nov 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Thanks for updating your PR! It now meets our contributing guidelines. 👍

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both earlier points are addressed. shell.openExternal now runs only on the user's Open click, never on the agent's request, and a double click opens the browser once. The tool description now matches the skill text: the pane stays signed out. I couldn't run the flow because it needs the desktop app; the updated handoff.test.ts, connection.test.ts and rpc.test.ts pass, and plugin-browser and gui-plugins type-check clean with tsc.

Public API: since the last review, the internal IPC handoff action also accepts open, and the handoff pane event gains the opened and failed states and an optional url. These are internal to the desktop. The tool's { state, host } result is unchanged, so it stays backwards compatible.

No new concerns.

@wra-sol

wra-sol commented Nov 17, 2026

Copy link
Copy Markdown
Author

The CI workflows (check, check-test, check-nix, check-bot-scope) are waiting on approval to run, as this is my first PR here — a maintainer clicking Approve and run on any of them would be welcome. For what it's worth, I've already run their content locally: bun run check passes repo-wide (lint + the 35-package typecheck) and the affected packages' unit tests pass (gui-plugins 1150/1150, plugin-browser 81/81).

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new commits only merge dev, and the pull request's own changes are the same as in my last review. The handoff and RPC tests still pass after the merges. Both earlier points were addressed in b42b5d02a: the system browser opens only on the user's Open click, and the tool description says the pane stays signed out. The public API is the same as in my last review: it adds the browser.handoff operation, a BrowserPane handoff IPC method and a handoff pane event, all backwards compatible. No new concerns.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new commit only merges dev. This pull request's own code is the same as in my last review. Both earlier points were addressed in b42b5d02a: the browser opens only on the user's Open click, and the tool description says the pane stays signed out. The public API is unchanged since then: it adds the browser.handoff operation, a BrowserPane handoff IPC method and a handoff pane event, all backwards compatible. No new concerns.

This branch has not been deployed

No deployments
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.

1 participant