Getting Started
Overview
Understand how the direct plugin, QR plugin, signer bridge, and test package fit together.
Overview
nimiq-pay-auth is a pnpm monorepo for two related Better Auth flows.
- The direct flow runs entirely inside a Nimiq Pay mini-app and signs in immediately.
- The QR flow starts on desktop, moves the approval step to the phone, and creates the Better Auth session on the desktop side.
Packages
| Package | Purpose |
|---|---|
@onmax/better-auth-nimiq-pay | Direct Nimiq Pay sign-in for Better Auth |
@onmax/better-auth-mobile-qr | Same-origin QR challenge, approval, and desktop session claim |
@onmax/mobile-signer-bridge | Generic phone-side bridge contract |
@onmax/mobile-signer-nimiq-pay | Nimiq Pay adapter for the bridge and QR provider |
@onmax/better-auth-nimiq-pay-e2e | Shared local fetchers, stub providers, and Vitest-first scenarios |
How the flows differ
Direct flow
The direct plugin issues a nonce, asks the mini-app to sign a message, verifies the signature, and returns a Better Auth bearer token or session. Use this when the current browser already has access to window.nimiq.
QR flow
The QR plugin creates a pending desktop challenge, stores a poll cookie, exposes the challenge to the phone page, accepts the signed phone assertion, and creates the Better Auth session only when the desktop polls the status endpoint again.