From df3cfdd7b721962a20e05a8ae866d0b9c6aa6a76 Mon Sep 17 00:00:00 2001 From: Arnaud Dagnelies Date: Thu, 5 Sep 2024 14:08:05 +0000 Subject: [PATCH] readme update --- README.md | 20 ++++---------------- docs/index.md | 21 +++++---------------- 2 files changed, 9 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index c46352a..4cda614 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ By default, this triggers the native passkey selection dialog, for any authentic ``` import {server} from '@passwordless-id/webauthn' await server.verifyRegistration(registration, expected) -await server.verifyAuthentication(registration, expected) +await server.verifyAuthentication(authentication, expected) ``` [→ Verification docs](https://webauthn.passwordless.id/verification/) @@ -124,21 +124,9 @@ Basically, this library is just a tool to realize something bigger. If you just 📃 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. +The version 2 introduced breaking changes, different default behavior and different intermediate format. Basically, it's a complete overhaul and to understand "why" this version 2 was made, I recommend reading this [blog post](https://blog.passwordless.id/passkeys-webauthn-library-v20-is-there#heading-why-a-version-2). In a very summarized way, it is to enhance support for security keys by default, reflect latest changes in the underlying specs and improve cross-compatibility with other server side libraries. + +Some core changes are: - Use platform authenticator by default => authenticator selection pops up by default - `authenticatorType` was removed => use `hints` instead diff --git a/docs/index.md b/docs/index.md index c1e5e22..b9e4c7b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,7 @@ @passwordless-id/webauthn ========================= +
[![NPM Version](https://img.shields.io/npm/v/%40passwordless-id%2Fwebauthn)](https://www.npmjs.com/package/@passwordless-id/webauthn) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@passwordless-id/webauthn)](https://bundlephobia.com/package/@passwordless-id/webauthn) @@ -8,6 +9,7 @@ [![GitHub Repo stars](https://img.shields.io/github/stars/passwordless-id/webauthn)](https://github.com/passwordless-id/webauthn) [![GitHub Sponsors](https://img.shields.io/github/sponsors/passwordless-id?style=social&logo=githubsponsors)](https://github.com/sponsors/passwordless-id) +
![banner](img/banner-biometric-auth.svg) @@ -102,7 +104,7 @@ By default, this triggers the native passkey selection dialog, for any authentic ``` import {server} from '@passwordless-id/webauthn' await server.verifyRegistration(registration, expected) -await server.verifyAuthentication(registration, expected) +await server.verifyAuthentication(authentication, expected) ``` Look at the docs for [registration](/registration/) and [authentication](/authentication/) for the corresponding verification examples. Or simply interact with real-life examples in the [Testing Playground](/demos/playground.html). @@ -129,22 +131,9 @@ Basically, this library is just a tool to realize something bigger. If you just 📃 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. +The version 2 introduced breaking changes, different default behavior and different intermediate format. Basically, it's a complete overhaul and to understand "why" this version 2 was made, I recommend reading this [blog post](https://blog.passwordless.id/passkeys-webauthn-library-v20-is-there#heading-why-a-version-2). In a very summarized way, it is to enhance support for security keys by default, reflect latest changes in the underlying specs and improve cross-compatibility with other server side libraries. +Some core changes are: - Use platform authenticator by default => authenticator selection pops up by default - `authenticatorType` was removed => use `hints` instead