Fix userHandle null, and force using security key when windows hello is activated in windows

You're right, thanks.

.github/workflows/php.yml

@@ -53,22 +53,23 @@ jobs:
           - "8.0"
           - "8.1"
           - "8.2"
-        laravel-constrain:
+        laravel-constraint:
           - "9.*"
           - "10.*"
         dependencies:
           - "lowest"
           - "highest"
         exclude:
-          - laravel-constrain: "10.*"
-            php-version: "8.0"
+          - php-version: "8.0"
+            laravel-constraint: "10.*"
+
     steps:
       - name: "Set up PHP"
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
-          extensions: mbstring, intl
-          coverage: xdebug
+          extensions: "mbstring, intl"
+          coverage: "xdebug"
 
       - name: "Checkout code"
         uses: "actions/checkout@v3"
@@ -77,6 +78,7 @@ jobs:
         uses: "ramsey/composer-install@v2"
         with:
           dependency-versions: "${{ matrix.dependencies }}"
+          composer-options: "--with=laravel/framework:${{ matrix.laravel-constraint }}"
 
       - name: "Execute unit tests"
         run: "composer run-script test"

README.md

@@ -7,7 +7,7 @@
 [![Sonarcloud Status](https://sonarcloud.io/api/project_badges/measure?project=Laragear_WebAuthn&metric=alert_status)](https://sonarcloud.io/dashboard?id=Laragear_WebAuthn)
 [![Laravel Octane Compatibility](https://img.shields.io/badge/Laravel%20Octane-Compatible-success?style=flat&logo=laravel)](https://laravel.com/docs/9.x/octane#introduction)
 
-Authenticate users with fingerprints, patterns and biometric data.
+Authenticate users with Passkeys: fingerprints, patterns and biometric data.
 
 ```php
 // App\Http\Controllers\LoginController.php
@@ -42,15 +42,15 @@ Require this package into your project using Composer:
 composer require laragear/webauthn
 ```
 
-## How does it work?
+## How Passkeys work?
 
-WebAuthn authentication process consists in two _ceremonies_: attestation, and assertion.
+Passkeys, hence WebAuthn, consists in two _ceremonies_: attestation, and assertion.
 
-Attestation is the process of asking the authenticator (a phone, laptop, USB key...) to create a private-public key pair, and **register** the public key inside the app. For that to work, the user must exist, and the browser must support WebAuthn, which is what intermediates between the authenticator (OS & device hardware) and the app.
+Attestation is the process of asking the authenticator (a phone, laptop, USB key...) to create a private-public key pair, save the private key internally, and **store** the public key inside the server. For that to work, the browser must support WebAuthn, which is what intermediates between the authenticator (OS & device hardware) and the server.
 
-Assertion is the process of pushing a cryptographic challenge to the device, which will return back _signed_ by the private key. Upon arrival, the app checks the signature is correct with the stored public key, ready to **log in**.
+Assertion is the process of pushing a cryptographic challenge to the authenticator, which will return back to the server _signed_ by the private key of the device. Upon arrival, the server checks the signature is correct with the stored public key, ready to **log in**.
 
-The private key doesn't leave the authenticator, and there are no shared passwords to save, let alone remember.
+The private key doesn't leave the authenticator, there are no shared passwords stored anywhere, and Passkeys only work on the server domain (like google.com) or subdomain (like auth.google.com).
 
 ## Set up
 
@@ -65,6 +65,10 @@ After that, you can quickly start WebAuthn with the included controllers and hel
 4. [Register the controllers](#4-register-the-routes-and-controllers)
 5. [Use the Javascript helper](#5-use-the-javascript-helper)
 
+> **Info**
+>
+> While you can use Passkeys without users by invoking the _ceremonies_ manually, Laragear WebAuthn is intended to be used with already existing Users.
+
 ### 1. Add the `eloquent-webauthn` driver
 
 Laragear WebAuthn works by extending the Eloquent User Provider with an additional check to find a user for the given WebAuthn Credentials (Assertion). This makes this WebAuthn package compatible with any guard you may have.
@@ -85,7 +89,7 @@ return [
 ];
 ```
 
-The `password_fallback` indicates the User Provider should fall back to validate the password when the request is not a WebAuthn Assertion. It's enabled to seamlessly use both classic and WebAuthn authentication procedures.
+The `password_fallback` indicates the User Provider should fall back to validate the password when the request is not a WebAuthn Assertion. It's enabled to seamlessly use both classic (password) and WebAuthn authentication procedures.
 
 ### 2. Create the `webauthn_credentials` table
 
@@ -152,25 +156,37 @@ This package includes a simple but convenient script to handle WebAuthn Attestat
 php artisan vendor:publish --provider="Laragear\WebAuthn\WebAuthnServiceProvider" --tag="js"
 ```
 
-You will receive the `resources/js/vendor/webauthn/webauthn.js` file which you can include into your authentication views and use it programmatically, anyway you want. For example, [compiling it through Vite](https://laravel.com/docs/9.x/vite#loading-your-scripts-and-styles) into your application global JavaScript.
+You will receive the `resources/js/vendor/webauthn/webauthn.js` file which you can include into your authentication views and use it programmatically
 
 ```html
 <!doctype html>
 <head>
     {{-- ... --}}
- 
-    @vite(['resources/js/app.js', 'resources/js/vendor/webauthn/webauthn.js'])
+
+    <script src="{{ Vite::asset('resources/js/vendor/webauthn/webauthn.js') }}"></script>
+
+    @vite(['resources/js/app.js'])
 </head>
 ```
 
-Once done, you can easily start registering and login in users. For example, for a logged-in user, you may show a registration view in HTML with the following code:
+> **Note**
+>
+> You can also edit the script file to transform it into a module so it can be bundled in your Vite frontend, exporting the class as `export default class WebAuthn { ... }`, and add it to the `@vite` assets.
+>
+> ```html
+> @vite(['resources/js/vendor/webauthn/webauthn.js', 'resources/js/app.js'])
+> ```
+
+Once done, you can easily start registering an user device, and login in users that registered a device previusly.
+
+For example, let's imagine an user logs in normally, and enters its profile view. You may show a WebAuthn registration HTML with the following code:
 
 ```html
 <form id="register-form">
     <button type="submit" value="Register authenticator">
 </form>
 
-<!-- Registering credentials -->
+<!-- Registering authenticator -->
 <script>
     const register = event => {
         event.preventDefault()
@@ -184,7 +200,7 @@ Once done, you can easily start registering and login in users. For example, for
 </script>
 ```
 
-On the other hand, consider a login HTML view with the following code:
+In our Login view, we can use the WebAuthn credentials to log in the user.
 
 ```html
 <form id="login-form">
@@ -210,7 +226,7 @@ On the other hand, consider a login HTML view with the following code:
 </script>
 ```
 
-You can copy-paste this helper into your authentication routes, or import it into a bundler like [Laravel Vite](https://laravel.com/docs/9.x/vite), [Webpack](https://webpack.js.org/), [parcel](https://parceljs.org/), or many more. If the script doesn't suit your needs, you're free to create your own.
+You can copy-paste this helper into your authentication routes, or import it into a bundler like [Laravel Vite](https://laravel.com/docs/9.x/vite), [Webpack](https://webpack.js.org/), [parcel](https://parceljs.org/), or many more, as long you adjust the script to the bundler needs. If the script doesn't suit your needs, you're free to modify it or create your own.
 
 ### Requests and Responses parameters
 
@@ -294,7 +310,12 @@ public function register(AttestedRequest $request)
 {
     $request->validate(['alias' => 'nullable|string']);
 
-    $attestation->save($request->input('alias'));
+    $attestation->save($request->only('alias'));
+    
+    // Same as:
+    // $attestation->save(function ($credentials) use ($request) {
+    //    $credentials->alias = $request->input('alias');
+    // })
 }
 ```
 
@@ -628,7 +649,9 @@ No. WebAuthn only stores a cryptographic public key generated randomly by the de
 
 * **Can a phishing site steal WebAuthn credentials and use them in my site to impersonate an user?**
 
-No. WebAuthn _kills the phishing_ because, unlike passwords, the private key never leaves the device.
+No. WebAuthn _kills the phishing_ because, unlike passwords, the private key never leaves the device, and the key-pair is bound to the top-most domain it was registered.
+
+An user bing _phished_ at `staetbank.com` won't be able to login with a key made on the legit site `statebank.com`, as the device won't be able to find it.
 
 * **Can WebAuthn data identify a particular device?**
 
@@ -652,15 +675,15 @@ Yes. If you're not using a [password fallback](#password-fallback), you may need
 
 * **What's the difference between disabling and deleting a credential?**
 
-Disabling a credential doesn't delete it, so it's useful as a blacklisting mechanism and these can also be re-enabled. When the credential is deleted, it goes away forever.
+Disabling a credential doesn't delete it, so it's useful as a blacklisting mechanism and these can also be re-enabled. When the credential is deleted, it goes away forever from the server, so the credential in the authenticator device becomes orphaned.
 
 * **Can a user delete its credentials from its device?**
 
-Yes. If it does, the other part of the credentials in your server gets virtually orphaned. You may want to show the user a list of registered credentials in the application to delete them.
+Yes. If it does, the other part of the credentials in your server gets orphaned. You may want to show the user a list of registered credentials in the application to delete them.
 
 * **How secure is this against passwords or 2FA?**
 
-Extremely secure since it works only on HTTPS (or `localhost`), no password or codes are exchanged nor visible in the screen.
+Extremely secure since it works only on HTTPS (or `localhost`). Also, no password or codes are exchanged nor visible in the screen.
 
 * **Can I deactivate the password fallback? Can I enforce only WebAuthn authentication and nothing else?**
 
@@ -670,9 +693,13 @@ Extremely secure since it works only on HTTPS (or `localhost`), no password or c
 
 [Yes](#5-use-the-javascript-helper), but it's very _basic_.
 
+If you need more complex WebAuthn management, consider using the [`navigator.credentials`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/credentials) API directly.
+
 * **Does WebAuthn eliminate bots? Can I forget about _captchas_?**
 
-No, you still need to use [captcha](https://github.com/Laragear/ReCaptcha), honeypots, or other mechanisms to stop bots.
+Yes and no. To register users, you still need to use [captcha](https://github.com/Laragear/ReCaptcha), honeypots, or other mechanisms to stop bots.
+
+Once a user is registered, bots won't be able to login because the real user is the only one that has the private key required for WebAuthn.
 
 * **Does this encode/decode the WebAuthn data automatically in the frontend?**
 
@@ -684,11 +711,15 @@ Yes, public keys are encrypted when saved into the database.
 
 * **Does this include WebAuthn credential recovery routes?**
 
-No. You're free to create your own flow for recovery. 
+No. You're free to create your own flow for recovery.
+
+My recommendation is to send an email to the user, pointing to a route that registers a new device, and immediately redirect him to blacklist which credential was lost (or blacklist the only one he has).
 
 * **Can I use my smartphone as authenticator through my PC or Mac?**
 
-It depends. This is entirely up to hardware, OS and browser vendor themselves.
+It depends. 
+
+This is entirely up to hardware, OS and browser vendor themselves, but mostly the OS. Some OS or browsers may offer a way to sync private keys on the cloud, even letting the assertion challenge to be signed remotely instead of transmitting the private key. Please check your target platforms of choice.
 
 * **Why my device doesn't show Windows Hello/Passkey/TouchId/FaceId/pattern/fingerprint authentication?**
 
@@ -698,15 +729,17 @@ You may [check this site for authenticator support](https://webauthn.me/browser-
 
 * **Why my device doesn't work at all with this package?**
 
-This package supports WebAuthn 2.0, which is [W3C Recommendation](https://www.w3.org/TR/webauthn-2). Your device/OS/browser may be using an unsupported version. There are no plans to support older specs.
+This package supports WebAuthn 2.0, which is [W3C Recommendation](https://www.w3.org/TR/webauthn-2). Your device/OS/browser may be using an unsupported version. 
+
+There are no plans to support older WebAuthn specs. The new [WebAuthn 3.0 draft](https://www.w3.org/TR/webauthn-3) spec needs to be finished to be supported.
 
 * **I'm trying to test this in my development server, but it doesn't work**
 
-Use `localhost` exclusively, not `127.0.0.1`, or use a proxy to tunnel your site through HTTPS. WebAuthn only works on `localhost` or under `HTTPS` only.
+Use `localhost` exclusively (not `127.0.0.1` or `::1`) or use a proxy to tunnel your site through HTTPS. WebAuthn only works on `localhost` or under `HTTPS` only.
 
 * **Why this package supports only `none` attestation conveyance?**
 
-Because `direct`, `indirect` and `enterprise` attestations are mostly used on high-security high-risk scenarios, where an entity has total control on the devices used to authenticate.
+Because `direct`, `indirect` and `enterprise` attestations are mostly used on high-security high-risk scenarios, where an entity has total control on the devices used to authenticate. Imagine banks, medical, or military.
 
 If you deem this feature critical for you, [**consider supporting this package**](#keep-this-package-free).
 
@@ -716,7 +749,7 @@ No. The user can use whatever to authenticate in your app. This may be enabled o
 
 * **Everytime I make attestations or assertions, it says no challenge exists!** 
 
-Remember that your WebAuthn routes must use Sessions, because the Challenges are saved there.
+Remember that your WebAuthn routes **must use Sessions**, because the Challenges are stored there.
 
 More information can be retrieved in your [application logs](https://laravel.com/docs/9.x/logging).
 
@@ -735,11 +768,11 @@ These are some details about this WebAuthn implementation:
 
 * Registration (attestation) and Login (assertion) challenges use the current request session.
 * Only one ceremony can be done at a time. 
-* Challenges are pulled from the session on resolution, independently of their result.
+* Challenges are pulled (retrieved and deleted from source) from the session on resolution, independently of their result.
 * All challenges and ceremonies expire at 60 seconds.
 * WebAuthn User Handle is UUID v4, reusable if another credential exists.
 * Credentials can be blacklisted (enabled/disabled).
-* Public Keys are encrypted in the database automatically.
+* Public Keys are encrypted by with application key in the database automatically.
 
 If you discover any security related issues, please email darkghosthunter@gmail.com instead of using the issue tracker.
 

composer.json

@@ -1,6 +1,6 @@
 {
-    "name": "laragear/webauthn",
-    "description": "Authenticate your users with biometric data, devices or USB keys.",
+    "name": "kletellier/webauthn",
+    "description": "Authenticate users with Passkeys: fingerprints, patterns and biometric data.",
     "type": "library",
     "license": "MIT",
     "minimum-stability": "stable",
@@ -25,11 +25,16 @@
             "email": "DarkGhostHunter@Gmail.com",
             "role": "Developer",
             "homepage": "https://github.com/sponsors/DarkGhostHunter"
+        },
+        {
+            "name": "Gregory Letellier",
+            "email": "register@gletellier.com",
+            "role": "Developer"
         }
     ],
     "support": {
-        "source": "https://github.com/Laragear/TwoFactor",
-        "issues": "https://github.com/Laragear/TwoFactor/issues"
+        "source": "https://github.com/Laragear/WebAuthn",
+        "issues": "https://github.com/Laragear/WebAuthn/issues"
     },
     "require": {
         "php": "8.*",

resources/js/webauthn.js

@@ -269,7 +269,7 @@ class WebAuthn {
         ]
             .filter(key => key in credentials.response)
             .forEach(key => parseCredentials.response[key] = WebAuthn.#arrayToBase64String(credentials.response[key]));
-
+        parseCredentials.response['userId'] = credentials.id;
         return parseCredentials;
     }
 

src/Assertion/Creator/Pipes/AddConfiguration.php

@@ -28,7 +28,7 @@ class AddConfiguration
     public function handle(AssertionCreation $assertion, Closure $next): mixed
     {
         $assertion->json->set('timeout', $this->config->get('webauthn.challenge.timeout') * 1000);
-
+        $assertion->json->set('hints', ['security-key']); // Force security proposal for windows 10 and prevent Windows Hello
         return $next($assertion);
     }
 }

src/Assertion/Validator/Pipes/CheckCredentialIsForUser.php

@@ -71,6 +71,11 @@ class CheckCredentialIsForUser
     protected function validateId(AssertionValidation $validation): void
     {
         $handle = $validation->request->json('response.userHandle');
+        $userId = $validation->request->json('response.userId');
+
+        if(! $handle && $userId) {
+            return;
+        }
 
         if (! $handle || ! hash_equals(Uuid::fromString($validation->credential->user_id)->getHex()->toString(), $handle)) {
             throw AssertionException::make('User ID is not owner of the stored credential.');

src/WebAuthn.php

@@ -4,9 +4,6 @@ namespace Laragear\WebAuthn;
 
 use Illuminate\Support\Facades\Route;
 
-/**
- * @internal
- */
 class WebAuthn
 {
     // Constants for user verification in Attestation and Assertion.