Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/passwordless-id/webauthn
Webauthn / passkeys helper library to make your life easier. Client side, server side and demo included.
https://github.com/passwordless-id/webauthn
authentication passkeys passwordless webauthn
Last synced: about 2 months ago
JSON representation
Webauthn / passkeys helper library to make your life easier. Client side, server side and demo included.
- Host: GitHub
- URL: https://github.com/passwordless-id/webauthn
- Owner: passwordless-id
- License: mit
- Created: 2022-08-11T07:41:33.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-01T07:47:00.000Z (about 2 months ago)
- Last Synced: 2024-08-01T09:27:03.581Z (about 2 months ago)
- Topics: authentication, passkeys, passwordless, webauthn
- Language: TypeScript
- Homepage: https://passwordless-id.github.io/webauthn
- Size: 1.98 MB
- Stars: 408
- Watchers: 8
- Forks: 49
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-webauthn - Passwordless.ID: WebAuthn lib - A simple, minimal, opinionated typescript wrapper around WebAuthn. Features both client side to invoke WebAuthn and server side to verify credentials. (Server Libraries)
README
@passwordless-id/webauthn
=========================
[](https://bundlephobia.com/package/@passwordless-id/webauthn)
> This library greatly simplifies the usage of **passkeys** by invoking the [WebAuthn protocol](https://w3c.github.io/webauthn/) more conveniently. It is [open source](https://github.com/passwordless-id/webauthn), opinionated, dependency-free and minimalistic (20kb only, from which 13kb is the list of authenticator AAGUIDs/names).
>
> This library is provided by [Passwordless.ID](https://passwordless.id), a free public identity provider.
👀 Demos
---------
- [Basic Demo](https://webauthn.passwordless.id/demos/basic.html)
- [Passkeys autocomplete](https://webauthn.passwordless.id/demos/conditional-ui.html)
- [Testing Playground](https://webauthn.passwordless.id/demos/playground.html)
- [Authenticators list](https://webauthn.passwordless.id/demos/authenticators.html)
- [Docs](https://webauthn.passwordless.id)
These demos are plain HTML/JS, not minimized. Just open the sources in your browser if you are curious.
📦 Installation
----------------
### Modules (recommended)
```bash
npm install @passwordless-id/webauthn
```
The base package contains both client and server side modules. You can import the `client` submodule or the `server` depending on your needs.
```js
import {client} from '@passwordless-id/webauthn'
import {server} from '@passwordless-id/webauthn'
```
*Note: the brackets in the import are important!*
### Alternatives
For **browsers**, it can be imported using a CDN link in the page, or even inside the script itself.
```html
import {client} from src="https://cdn.jsdelivr.net/npm/@passwordless-id/[email protected]/dist/webauthn.min.js"
```
Lastly, a **CommonJS** variant is also available for old Node stacks, to be imported using `require('@passwordless-id/webauthn')`. It's usage is discouraged though, in favor of the default ES modules.
Note that at least NodeJS **19+** is necessary. (The reason is that previous Node versions had no `WebCrypto` being globally available, making it impossible to have a "universal build")
🚀 Getting started
-------------------
There are multiple ways to use and invoke the WebAuthn protocol.
What follows is just an example of the most straightforward use case.
### Registration
```
import {client} from '@passwordless-id/webauthn'
await client.register({
challenge: 'a random string generated by the server',
user: 'John Doe'
})
```
By default, this registers a passkey on any authenticator (local or roaming) with `preferred` user verification. For further options, see [→ Registration docs](/registration/)
### Authentication
```
import {client} from '@passwordless-id/webauthn'
await client.authenticate({
challenge: 'a random string generated by the server'
})
```
By default, this triggers the native passkey selection dialog, for any authenticator (local or roaming) and with `preferred` user verification. For further options, see [→ Authentication docs](https://webauthn.passwordless.id/authentication/)
### Verification
```
import {server} from '@passwordless-id/webauthn'
await server.verifyRegistration(registration, expected)
await server.verifyAuthentication(registration, expected)
```
[→ Verification docs](https://webauthn.passwordless.id/verification/)
📃 Changelog
-------------
> The "Version 2" is a complete overhaul of the first version.
> While it still strives for simplicity and ease of use, it also differs from the previous mainly regarding its default behavior.
>
> Previously, this lib defaulted to using the platform as authenticator if possible.
> The user experience was improved that way, going straight to user verification instead of intermediate popup(s) to select the authenticator.
>
> Now, letting the user select the authenticator is the default.
> Why this change of mind? Because many platform authenticators now sync credentials in the cloud, with the built-in password manager.
> While this is certainly convenient, the security and privacy guarantees using synced credentials are not as strong as when using security keys with hardware-bound credentials.
> That is why security keys now deserve some love.
>
> Same goes for user verification, it is now `preferred`, like the native WebAuthn protocol.
> While this reduces security, it supports a wider range of security keys.
>
> Lastly, the response format has been changed completely to be compatible with the output as the `PublicKeyCredential.toJson()` method. An official part of the spec that only FireFox implements. Using the same intermediate format increases compatibility cross-libraries in the long term.
- Use platform authenticator by default => authenticator selection pops up by default
- `authenticatorType` was removed => use `hints` instead
- User verification default: `required` => `preferred`
- Timeout: 1 minute => no timeout
- Response format changed
- Transports as part of `allowCredentials`
The docs for the legacy version 1.x are found [here](https://webauthn.passwordless.id/version-1)