...

_config.yml

@@ -9,14 +9,7 @@ author: Arnaud Dagnelies
 navbar-var-length: true
 
 navbar-links:
-  F.A.Q.:
-    - Is it "production ready"?: faq/TODO
-    - Is it scalable?: faq/TODO
-    - Why is it better than rolling your own?: faq/TODO
-    - How can this be free?: faq/TODO
-    - Is it secure?: faq/TODO
-    - What about privacy?: faq/TODO
-    - What if I loose my device?: faq/TODO
+  F.A.Q.: faq/index
   Getting Started:
     - Javascript - Vanilla: getting_started/javascript_spa
     - Python - FastAPI: https://github.com/passwordless-id/fast-api-demo

faq/index.md

@@ -0,0 +1,80 @@
+For Devs
+========
+
+Is it "production-ready"?
+-------------------------
+
+Let's be honest, it is **not** *yet*. It works, it's secure, it's usable,
+but it is still slightly incomplete and lacks the polish to really use it in production right now. 
+It's more in a proof-of-concept stage than a finished service.
+
+Is it scalable?
+---------------
+
+**Yes**, it is. We use so called "edge computing" and a distributed database. Basically, the code is distributed on hundreds of data-centers around the globe and the code invoked on-demand. This ensures infinite scalability, elasticity to handle bursts and optimal latency for every location.
+
+Who are we?
+-----------
+
+Let's not beat around the bush, the "*we*" is an "*I*". That's right, this is a solo endeavor. Who am I?
+Arnaud Dagnelies, a senior software developer in the fortys, living in Germany, having programmed since high-school.
+
+Why is it better than rolling your own?
+---------------------------------------
+
+There are two reasons for this. The first is that it's a lot of work rolling your own. It's not just understanding and invoking the complex WebAuthn protocol.
+It's managing fallbacks in case the browser does not support it, recovery mechanisms, enrolling multiple devices, managing the profile, ensuring security, updates...
+
+The other is related to user comfort. Since the WebAuthn/Passkeys protocol is device/account bound, the user has to register multiple devices ...and it's no fun to do that for every website. It's much more comfortable to do it in a single place. That's why I'm convinced the "Sign in with ..." will remain more popular than "Duh, I have to register my devices here again".
+
+
+How can this be free?
+---------------------
+
+It is our conviction that making it publicly available is the best way to make the internet a safer place as a whole.
+We want to keep it free for everyone and forever without catch.
+
+However, being free is not sustainable in the long term. We need food on the plate. [Sponsors welcome!](https://github.com/sponsors/passwordless-id)
+
+
+For Users
+=========
+
+Is it secure?
+-------------
+
+Yes, it is. Security comes from multiple aspects, but the core is the protocol.
+You basically require a key stored on your device (*) and a local user verification to sign in.
+This results in a two-factor authentication in a single step:
+
+- Something you have
+- Something you are or know (in case of biometric or PIN verification)
+
+In a later stage, it's also planned to add further security using an optional third factor: your location.
+
+
+(*) Is it really device bound?
+------------------------------
+
+Yes and no. The underlying WebAuthn protocol enables us to "prefer" device-bound credentials but not enforce it.
+As of speaking, Windows, Android, Linux and USB keys do use device-bound credentials.
+On the opposite, Apple always syncs the credentials on all your devices, like password managers.
+
+
+What if I loose my device?
+--------------------------
+
+Passwordless.ID enables you to register multiple devices from multiple operating systems.
+Adding a device is as simple as scanning a QR code or clicking on a link received per e-mail.
+
+However, *if* you loose all your registered devices *and* have no recovery mechanisms in place (like an e-mail or SMS), then yes, you inccur the risk of locking yourself out of your account. Therefore, we highly recommend to register multiple devices or fill e-mail and phone number in your profile.
+
+
+What about privacy?
+-------------------
+
+We do not use, resell nor exchange your data with anyone else.
+Everything that you write here stays here, except if you give explicit consent to share part of your profile information with another website.
+We do not track (yet) your activity (like when you sign-in and from where), but we plan to do so in the future for the sole purpose of intrusion attempts detection and boosting security even further. Like before, this data will not be sent to any third-party.
+
+

protocols/oauth2/2_authorize.md

@@ -11,12 +11,12 @@ If the user is already authenticated and has already granted permissions, the ca
 | `client_id`    | The unique identifier assigned to the client application by the authorization server.        |
 | `redirect_uri` | The URI to which the authorization server will redirect the user after successful authentication and authorization. |
 | `response_type` | Specifies the type of response the application expects. For the Authorization Code Flow, this should be set to "code" to indicate that the application is requesting an authorization code. |
-| `state`        | A unique and random value generated by the client application to prevent cross-site request forgery (CSRF) attacks. |
 
 ### Optional Parameters
 
 | Parameter      | Description                                                                                               |
 |----------------|-----------------------------------------------------------------------------------------------------------|
+| `state`        | *Recommended*. An opaque value used by the client to maintain state between the request and callback. This value is included when redirecting the user-agent back to the client. It also helps to prevent cross-site-request-forgery, where an attacker sends its own authorization code to induce the user in manipulating the wrong resource. [More information here](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12) |
 | `acr_values`   | Specifies the level of authentication and attribute requirements. Largely unused/unsupported in practice. | 
 | `claims`       | Requests specific user claims to be included in the ID Token or UserInfo response.                        |
 | `code_challenge` | Used when implementing PKCE (Proof Key for Code Exchange) for added security.                           |

protocols/oauth2/3_token.md

@@ -0,0 +1,20 @@
+RFC: https://datatracker.ietf.org/doc/html/rfc6749
+
+**Authorization code**
+
+| Parameter     | Description                                          |
+| ------------- | ---------------------------------------------------- |
+| `grant_type`  | The type of grant requested (e.g., "authorization_code", "password", "client_credentials"). |
+| `redirect_uri` | The redirection URI to which the authorization server will send the user-agent after the user grants/denies consent. |
+| `code`        | The authorization code received from the authorization server (for the "authorization_code" grant type). |
+
+**Refresh token**
+
+| `client_id`   | The unique identifier of the client making the request. |
+| `client_secret` | The secret key or password associated with the client, used for client authentication. |
+| `username`    | The resource owner's username (for the "password" grant type). |
+| `password`    | The resource owner's password (for the "password" grant type). |
+| `scope`       | The scope of access requested by the client. Specifies what resources the client intends to access. |
+| `refresh_token` | A refresh token used to obtain a new access token when the original access token expires (for grant types that support refresh tokens). |
+
+**Other grants**