Passkey Auth Kit — Demo Wallet

Sample biometric smart wallet demonstrating passkey-based transaction signing on Stellar.

This repository contains the frontend application and TypeScript client SDK for Passkey Auth Kit. It provides a reference implementation for dApp developers integrating WebAuthn-based biometric signing — covering passkey onboarding, biometric login, and Secp256r1 transaction signing against Soroban smart contracts.

Related repository: passkey-auth-kit-core — Rust/Soroban Secp256r1 verification contracts and cryptographic test suite.

---

Why This Exists

Standard public-private key cryptography introduces significant UX friction for retail and institutional web3 adoption:

• Secret phrase and private key management is a primary vector for user error and phishing attacks.
• Mobile dApp users must frequently copy and paste private keys, exposing credentials to clipboard exploits.
• Existing smart contract wallets struggle to verify WebAuthn signatures natively without incurring high on-chain costs.
• Developers lack modular, ready-to-use templates to implement biometric multi-sig structures with customizable key-rotation policies.

---

Repository Structure

.
├── apps/
│   └── demo-wallet/                   # Next.js reference smart wallet
│       ├── app/
│       │   ├── onboarding/            # Passkey registration and device enrolment flow
│       │   ├── login/                 # Biometric authentication and session management
│       │   └── sign/                  # Transaction construction and biometric signing UI
│       ├── components/                # Shared UI — passkey prompts, status indicators, tx reviews
│       └── public/
├── packages/
│   └── wallet-sdk/                    # TypeScript client library
│       ├── src/
│       │   ├── passkey.ts             # WebAuthn credential creation and assertion handlers
│       │   ├── enclave.ts             # Hardware security enclave interface (Apple Secure Enclave, Android Keystore)
│       │   ├── soroban.ts             # Soroban transaction builder and contract invocation helpers
│       │   └── types.ts               # Shared SDK type definitions
│       ├── package.json
│       └── tsconfig.json
├── docs/                              # WebAuthn payload decoding, key rotation strategies,
│                                      # and security assumptions
├── .github/
│   └── SECURITY.md
├── .env.example
└── README.md

---

Quick Start

Prerequisites

• Node.js 22+, npm 10+
• A device with biometric security support (TouchID, FaceID, or Windows Hello)
• A deployed instance of the Secp256r1 verification contract (see passkey-auth-kit-core)

Environment Setup

cp .env.example .env.local

# Soroban contract address for Secp256r1 verification
NEXT_PUBLIC_CONTRACT_ID=your_deployed_contract_id

# Stellar network
NEXT_PUBLIC_STELLAR_NETWORK=testnet              # or mainnet
NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org

# Optional: passkey relying party config
NEXT_PUBLIC_RP_ID=localhost                      # your domain in production
NEXT_PUBLIC_RP_NAME=Passkey Auth Kit Demo

Run the Demo Wallet

cd apps/demo-wallet
npm install
npm run dev

The demo wallet will be available at http://localhost:3000.

Build the Wallet SDK

cd packages/wallet-sdk
npm install
npm run build

Build for Production

cd apps/demo-wallet
npm run build
npm start

---

Using the Wallet SDK

Install the SDK into your own project directly from the monorepo or once published:

npm install @passkey-auth-kit/wallet-sdk

Register a new passkey for a user:

import { createPasskey, signTransaction } from "@passkey-auth-kit/wallet-sdk";

// Register a new biometric credential
const credential = await createPasskey({
  username: "user@example.com",
  displayName: "Jane Doe",
});

// Sign a Soroban transaction with biometrics
const signedTx = await signTransaction({
  transaction: builtTransaction,
  credentialId: credential.id,
});

---

Security

To report a cryptographic or logic vulnerability, Create an issue.

The wallet-sdk interfaces directly with hardware security enclaves — private key material never leaves the device. All WebAuthn assertion payloads passed to the Soroban contract are verified on-chain against test vectors derived from the WebAuthn specification.

---

License

This project is currently unlicensed. Usage, redistribution, and modification restrictions are in place while the cryptographic implementation undergoes review. To request access or discuss licensing, please open an issue.