diff options
| -rw-r--r-- | README.md | 28 |
1 files changed, 28 insertions, 0 deletions
@@ -12,6 +12,30 @@ An additional package is also included that contains shared TypeScript definitio - [@webauthntine/typescript-types](./packages/typescript-types/) +See these packages' READMEs for more specific implementation information. + +## Philosophy + +WebAuthn is a browser API that enables the use of physical, cryptographically-secure hardware "authenticators" to provide stronger replacements to passwords or 2FA. + +Website back ends that wish to leverage this technology must be set up to do two things: + +1. Provide to the front end a specific collection of values that the hardware authenticator will understand for "registration" and "login". +2. Parse responses from a hardware authenticator. + +Website front ends have their own part to play in the process: + +1. Pass the server-provided values into `navigator.credentials.create()` and `navigator.credentials.get()` so the user can interact with their compatible authenticator. +2. Pass the authenticator's response returned from these methods back to the server. + +On the surface, this is a relatively straightforward dance. Unfortunately the values passed into the `navigator.credentials` methods and the responses received from them make heavy use of `ArrayBuffer`'s which are difficult to transmit as JSON between front end and back end. Not only that, there are many complex ways in which authenticator responses must be parsed, and though finalized, [the W3C spec](https://w3c.github.io/webauthn/) is quite complex and is being expanded all the time. + +**Enter WebAuthntine.** + +WebAuthntine attempts to offer a developer-friendly pair of libraries that simplify the above dance. [@webauthntine/server](./packages/server/) exports a small number of methods requiring a handful of simple inputs that pair with the two primary methods exported by [@webauthntine/browser](./packages/browser). No converting back and forth between `Uint8Array` (or was this supposed to be an `ArrayBuffer`...?) and `String`, no worrying about JSON compatibility - **WebAuthntine takes care of it all!** + +For a practical guide to implementing these to libraries, take a look at the [example project](./example). It includes a single-file Express server and a few HTML files that, combined with the packages in this repo, are close to all it takes to get up and running with WebAuthn. + ## Development After pulling down the code, set up dependencies: @@ -32,3 +56,7 @@ Running Jest in watch mode for a specific project requires the use of `lerna exe ```sh $> npx lerna exec npm run test:watch --scope=@webauthntine/server ``` + +## Pronunciation Guide + +It's pronounced **"web-authn-teen"**...because I couldn't stop thinking about rewatching the movie Constantine (with Keanu Reeves) when I was brainstorming project names. |