Skip to content

Conversation

@ahnafalfariza
Copy link
Collaborator

Pre-flight checklist

  • I have read the Contributing Guidelines on pull requests.
  • Commit messages follow the conventional commits spec
  • If this is a code change: I have written unit tests.
  • If this changes code in a published package: I have run pnpm changeset to create a changeset JSON document appropriate for this change.
  • If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

This pull request introduces the new @near-wallet-selector/webauthn-wallet package, enabling biometric authentication (WebAuthn) as a wallet option for NEAR Wallet Selector

Passkey Creation & Key Derivation

  • When a user signs in for the first time, the wallet creates a WebAuthn credential (passkey) using the browser's navigator.credentials.create() API
  • The passkey is stored securely in the device's Trusted Platform Module (TPM) or secure enclave
  • A deterministic NEAR Ed25519 keypair is derived from the passkey's credential ID using SHA-256 hashing
  • This ensures the same passkey always generates the same NEAR keypair, enabling consistent account access

Account Creation Flow

  1. User enters a desired NEAR account ID
  2. System checks if the account exists on-chain
  3. If new account:
    • Creates a passkey via biometric authentication (fingerprint, face, PIN)
    • Derives NEAR keypair from the passkey's credential ID
    • Calls the configured relayer service to create the NEAR account with the derived public key
  4. If existing account:
    • Authenticates with existing passkey
    • Verifies the derived public key matches an access key on the account

Authentication & Transaction Signing

  • Sign In: Uses navigator.credentials.get() to authenticate with the stored passkey
  • Transaction Signing:
    • Displays transaction details in a modal for user review
    • Prompts for biometric authentication to access the private key
    • Signs transactions using the NEAR keypair derived from the passkey
    • Supports single transactions, batch transactions, message signing, and delegate actions

Storage & Session Management

  • Only stores public keys and account metadata in browser storage
  • Private keys never leave the secure hardware - they're re-derived from passkeys on each use
  • Maintains a list of previously used accounts for easy re-authentication
  • Supports multiple accounts per device

@changeset-bot
Copy link

changeset-bot bot commented Oct 17, 2025

🦋 Changeset detected

Latest commit: e545885

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 30 packages
Name Type
@near-wallet-selector/webauthn-wallet Minor
@near-wallet-selector/arepa-wallet Minor
@near-wallet-selector/bitget-wallet Minor
@near-wallet-selector/bitte-wallet Minor
@near-wallet-selector/coin98-wallet Minor
@near-wallet-selector/core Minor
@near-wallet-selector/ethereum-wallets Minor
@near-wallet-selector/here-wallet Minor
@near-wallet-selector/hot-wallet Minor
@near-wallet-selector/intear-wallet Minor
@near-wallet-selector/ledger Minor
@near-wallet-selector/math-wallet Minor
@near-wallet-selector/meteor-wallet-app Minor
@near-wallet-selector/meteor-wallet Minor
@near-wallet-selector/modal-ui-js Minor
@near-wallet-selector/modal-ui Minor
@near-wallet-selector/my-near-wallet Minor
@near-wallet-selector/narwallets Minor
@near-wallet-selector/near-mobile-wallet Minor
@near-wallet-selector/near-snap Minor
@near-wallet-selector/nightly Minor
@near-wallet-selector/okx-wallet Minor
@near-wallet-selector/ramper-wallet Minor
@near-wallet-selector/react-hook Minor
@near-wallet-selector/sender Minor
@near-wallet-selector/unity-wallet Minor
@near-wallet-selector/wallet-connect Minor
@near-wallet-selector/wallet-utils Minor
@near-wallet-selector/welldone-wallet Minor
@near-wallet-selector/xdefi Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@ahnafalfariza ahnafalfariza changed the title Feat/webauthn wallet Implement webauthn wallet Oct 17, 2025
roman009
roman009 previously approved these changes Oct 27, 2025
@roman009 roman009 merged commit 156b85e into main Oct 28, 2025
1 check passed
@roman009 roman009 deleted the feat/webauthn-wallet branch October 28, 2025 11:18
@github-actions github-actions bot mentioned this pull request Oct 28, 2025
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.

4 participants