Skip to content

feat: support the use-wallet passkey wallet - #85

Merged
drichar merged 8 commits into
mainfrom
feat/passkey
Nov 8, 2026
Merged

drichar merged 8 commits into
mainfrom
feat/passkey

Conversation

@drichar

@drichar drichar commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds support for the passkey wallet in use-wallet 5.2.0 (@txnlab/use-wallet-passkey) to both @txnlab/use-wallet-ui-react and @txnlab/use-wallet-ui-vue.

  • When an app registers passkey(), the connect dialog shows a Passkey group with Sign in with passkey and Create a passkey above the other wallets. passkeyLayout: 'featured' leads with a Continue with passkey button instead.
  • Passkey errors keep the dialog open with a message the user can act on: cancelled or no passkey found, an in-app browser, or a provider without PRF support.
  • A new opt-in ./plugins/passkey entry adds Back up account (Falcon / quantum recovery-phrase export), session Lock and Unlock, and an optional show-once note that the account belongs to this site.
  • The main entry keeps the ^4.6.0 || ^5.0.0 peer range. The plugin needs use-wallet 5.2+, which any app with the passkey wallet already has.

Details

Compatibility

  • Connecting only needs wallet.connect(args), which v4.6+ already has.
  • Only ./plugins/passkey imports useWalletManager(), which React and Vue added in 5.2. @txnlab/use-wallet-passkey peers on core ^5.2.0, and each framework adapter pins its core version, so an app with the passkey wallet always has it.
  • The adapter is typed structurally, with no runtime dependency on @txnlab/use-wallet-passkey. A type test fails if PasskeyAdapter stops matching.

Safari / iOS

  • Every handler calls connect, unlock or exportRecoveryPhrase before any await, so the browser keeps the user's tap.

Connect dialog

  • passkeyLayout can be set on WalletUIProvider, or per menu on WalletButton and ConnectWalletMenu. The menu setting wins; the default is 'list'.
  • PasskeyConnect is exported for custom menus. WalletList no longer renders the passkey wallet.
  • While the prompt is open, the control the user pressed shows a spinner and "Waiting for your passkey…", and the other control dims.

Connected menu

  • Passkey accounts get a domain tag, such as localhost.

passkeyPlugin()

  • Back up account: a fresh passkey prompt, then the 25-word phrase with Lute and Pera Falcon import steps. The phrase hides after a timeout (60s by default), lives only in component state, and the clipboard is cleared best-effort on close.
  • session: true: Locked or Unlocked status with Unlock and Lock.
  • disclosure: true: a note shown until "Got it", remembered per address in localStorage, with an in-memory fallback.

Examples and tests

  • New examples/react-passkey and examples/vue-passkey apps (passkey, Lute, Pera) with a layout selector.
  • New Chromium-only passkey-react and passkey-vue Playwright projects use the CDP virtual authenticator with PRF. They cover create, sign in, errors, the pending state, both layouts, session, recovery phrase, clipboard clearing, and dismissal, including when storage is blocked. CI now runs them.

Also fixed

  • pnpm build:examples failed on main for five examples: vite-plugin-node-polyfills injected shim imports into the workspace-linked dist files. The examples now alias the shims, and every polyfill stays on.

Apps that register passkey() from @txnlab/use-wallet-passkey (use-wallet
5.2+) now get it in the connect dialog with "Create passkey" and "Sign in"
buttons. Passkey errors keep the dialog open with a message the user can
act on (cancelled or no passkey found, in-app browser, no PRF support).
The connect call starts before any await, so Safari and iOS keep the tap.

A new ./plugins/passkey entry (React and Vue) adds to the connected menu:
- Export Recovery Phrase: a fresh passkey prompt, Falcon / quantum import
  instructions for Lute and Pera, a 60s timeout, and best-effort clipboard
  clearing
- Session lock status with Unlock and Lock (session: true)
- A note that the account belongs to the site (disclosure, on by default)

Only the plugin entry imports useWalletManager (use-wallet 5.2+), so the
main entry keeps the ^4.6.0 || ^5.0.0 peer range. The adapter is typed
structurally, with a type test against PasskeyAdapter; use-wallet-passkey
is a devDependency only.

Also:
- Bump use-wallet devDependencies and examples to 5.2.0
- Add react-passkey and vue-passkey examples (passkey, Lute, Pera)
- Add passkey-react and passkey-vue Playwright projects using Chromium's
  virtual authenticator with PRF, and run them in CI
- Document the plugin and the WalletList args contract
The connect dialog now leads with the passkey wallet: a full-width
"Continue with passkey" button signs in, and a "New here? Create a
passkey" link creates one. The other wallets follow under an "or connect
a wallet" divider. WalletList no longer renders the passkey wallet; the
section is exported as PasskeyConnect for custom connect menus.

The connected menu tags a passkey account with its domain. The plugin's
disclosure is now off by default; with `disclosure: true` it shows until
the user chooses "Got it", remembered per address in localStorage (with
an in-memory fallback when storage is unavailable).

Export Recovery Phrase uses a document icon, since a key now means
passkey sign-in.

Also restore the passkey plugin's Requirements and Subpath Import docs,
which the first passkey commit dropped from PLUGINS.md.
vite-plugin-node-polyfills injects its shim imports into every module,
including the workspace-linked packages/*/dist files. Those can't resolve
vite-plugin-node-polyfills, so `pnpm build:examples` failed for the react,
react-css-only, react-custom, react-web3auth and vue examples. CI doesn't
build the examples, so this went unnoticed.

Alias the three shims to their ESM files, resolved from each example. All
polyfills stay on (Web3Auth still gets its `process` global), and the
passkey examples drop their Buffer-only workaround for the same fix.
Connect dialogs can now present the passkey wallet two ways:
- 'featured' (default): the existing "Continue with passkey" button and
  "Create a passkey" link, with the other wallets below
- 'list': "Sign in with passkey" and "Create a passkey" rows in a Passkey
  group above a Wallets group, for apps where most users bring a wallet

Set it app-wide with `passkeyLayout` on WalletUIProvider, or per menu on
WalletButton or ConnectWalletMenu; the menu prop wins, and the default is
'featured'. PasskeyConnect takes a `layout` prop so custom menus get both,
and PasskeyConnectLayout is exported. The wallet icon tile moves into a
shared WalletIcon component.

The passkey examples get a Featured / List selector (or ?layout=list),
and e2e covers the list layout's rows, create and sign-in, the error
hint, and switching layouts through the provider.
The connect dialog now shows the passkey wallet as "Sign in with
passkey" and "Create a passkey" rows in a Passkey group above the other
wallets. `passkeyLayout: 'featured'` keeps the "Continue with passkey"
layout. PasskeyConnect defaults to 'list' as well.

The dialog now passes `layout="featured"` to PasskeyConnect explicitly
instead of relying on its default, which had shown the list rows for
'featured' once the default changed. The passkey examples start in the
list layout (?layout=featured opens the other), and the e2e suites set
their layout explicitly.
While a passkey prompt is open, the control the user pressed shows a
spinner and "Waiting for your passkey…" at full strength, and the other
control dims. Both layouts do this; the status line is now for screen
readers only. PasskeyConnectStatus gains an optional `action`
('sign-in' | 'create') to tell them apart.

The plugin's recovery item is now "Back up account" with a numbered-list
icon, tagged "Not backed up" until the phrase has been revealed once for
the account (remembered per address in localStorage, with an in-memory
fallback). `recoveryPhrase: { backupReminder: false }` turns the tag off.
The per-address storage for the disclosure and this flag now share one
helper (storage.ts).

The passkey e2e fixture can turn off presence simulation to hold a prompt
open, so the pending state is tested in both layouts. The examples' intro
copy now matches the list default.
The tag could only record that the recovery phrase had been shown, not
that the user backed it up, so it claimed more than the app can know.
Drop it along with the `recoveryPhrase.backupReminder` option and its
per-address storage flag. The menu item keeps its "Back up account"
label.
A solid shield (Heroicons shield-check without the check) reads as a
protective step without implying the backup is already done. A key
would read as passkey sign-in.
@drichar
drichar merged commit c2734e7 into main Nov 8, 2026
2 checks passed
txnlab-release-bot Bot added a commit that referenced this pull request Nov 8, 2026
# [1.4.0](v1.3.0...v1.4.0) (2026-11-08)

### Features

* support the use-wallet passkey wallet ([#85](#85)) ([c2734e7](c2734e7))
@txnlab-release-bot

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 1.4.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

drichar added a commit that referenced this pull request Nov 8, 2026
Vue is published by the manual Release Vue workflow, which publishes the
version in packages/vue/package.json. 1.2.0 carries the passkey support
from #85.
drichar added a commit that referenced this pull request Nov 8, 2026
Vue is published by the manual Release Vue workflow, which publishes the
version in packages/vue/package.json. 1.2.0 carries the passkey support
from #85.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant