webauthn
NPM: @hexagon\webauthn | Deno.land: webauthn
Slim DWebauthn library with ES6, Deno and Node support. Heavily based on fido2-lib.
Currently in pre-release
Demo/Example for both Deno and Node available at github.com/Hexagon/webauthn-skeleton/tree/server/deno
Features
- Supports both Deno and recent versions of Node
- ESM based code base
- Bundle distributable, no remote dependencies
Installation
Node.js
npm install @hexagon/webauthn --save
JavaScript
// ESM Import ...
import { Webauthn } from "@hexagon/webauthn";
// ... or CommonJS Require
const { Webauthn } = require("@hexagon/webauthn");
TypeScript
import { Webauthn } from "@hexagon/webauthn";
// ...
Deno
JavaScript
import webauthn from "https://cdn.jsdelivr.net/gh/hexagon/webauthn@0/lib/webauthn.js";
// ...
TypeScript
import { webauthn } from "https://cdn.jsdelivr.net/gh/hexagon/webauthn@0/lib/webauthn.js";
// ...
Documentation
Full documentation available at hexagon.github.io/webauthn.
Examples
Assuming you have imported webauthn as described under 'Installation'.
@hexagon/webauthn uses the same interface as fido2-lib
Examples from github.com/webauthn-open-source/fido2-lib:
Instantiate Library (Simple):
// create a new instance of the library
var f2l = new Webauthn();
Instantiate Library (Complex):
// could also use one or more of the options below,
// which just makes the options calls easier later on:
var f2l = new Fido2Lib({
timeout: 42,
rpId: "example.com",
rpName: "ACME",
rpIcon: "https://example.com/logo.png",
challengeSize: 128,
attestation: "none",
cryptoParams: [-7, -257],
authenticatorAttachment: "platform",
authenticatorRequireResidentKey: false,
authenticatorUserVerification: "required"
});
Registration:
var registrationOptions = await f2l.attestationOptions();
// make sure to add registrationOptions.user.id
// save the challenge in the session information...
// send registrationOptions to client and pass them in to `navigator.credentials.create()`...
// get response back from client (clientAttestationResponse)
var attestationExpectations = {
challenge: "33EHav-jZ1v9qwH783aU-j0ARx6r5o-YHh-wd7C6jPbd7Wh6ytbIZosIIACehwf9-s6hXhySHO-HHUjEwZS29w",
origin: "https://localhost:8443",
factor: "either"
};
var regResult = await f2l.attestationResult(clientAttestationResponse, attestationExpectations); // will throw on error
// registration complete!
// save publicKey and counter from regResult to user's info for future authentication calls
Authentication:
var authnOptions = await f2l.assertionOptions();
// add allowCredentials to limit the number of allowed credential for the authentication process. For further details refer to webauthn specs: (https://www.w3.org/TR/webauthn-2/#dom-publickeycredentialrequestoptions-allowcredentials).
// save the challenge in the session information...
// send authnOptions to client and pass them in to `navigator.credentials.get()`...
// get response back from client (clientAssertionResponse)
var assertionExpectations = {
// Remove the following comment if allowCredentials has been added into authnOptions so the credential received will be validate against allowCredentials array.
// allowCredentials: [{
// id: "lTqW8H/lHJ4yT0nLOvsvKgcyJCeO8LdUjG5vkXpgO2b0XfyjLMejRvW5oslZtA4B/GgkO/qhTgoBWSlDqCng4Q==",
// type: "public-key",
// transports: ["usb"]
// }],
challenge: "eaTyUNnyPDDdK8SNEgTEUvz1Q8dylkjjTimYd5X7QAo-F8_Z1lsJi3BilUpFZHkICNDWY8r9ivnTgW7-XZC3qQ",
origin: "https://localhost:8443",
factor: "either",
publicKey: "-----BEGIN PUBLIC KEY-----\n" +
"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAERez9aO2wBAWO54MuGbEqSdWahSnG\n" +
"MAg35BCNkaE3j8Q+O/ZhhKqTeIKm7El70EG6ejt4sg1ZaoQ5ELg8k3ywTg==\n" +
"-----END PUBLIC KEY-----\n",
prevCounter: 362
};
var authnResult = await f2l.assertionResult(clientAssertionResponse, assertionExpectations); // will throw on error
// authentication complete!
Full demo for both Deno and Node available at github.com/Hexagon/webauthn-skeleton/tree/server/deno
Contributing
See Contribution Guide for general guidelines.
Development
Command | Description |
---|---|
npm run build |
Run all sorts of checks (both Node and Deno), then builds the bundle, run before releasing |
deno fmt |
Format code base |
deno lint |
Lint code base |
deno test test/deno |
Run deno tests |
npm run test:node |
Run node tests |
File structure
Path | Description |
---|---|
/lib/common |
Source code base folder |
/lib/common/attestation |
Attestation plug-ins |
/lib/common/tools |
Bundled dependencies |
/lib/webauthn.js |
Deno entrypoint |
/lib/toolbox.js |
Deno external dependencies and shims |
/test/node |
Node tests |
/test/deno |
Deno tests |
/docs |
Documentation |
Dependency management
- Dependencies are imported by
deps.js
- Pre-bundled dependencies are placed in
lib/common/tools
- Node.js testing/dev-dependencies versions are managed in
package.json
Current dependencies
Package | Use | Version | From |
---|---|---|---|
tldts | Production (bundled in dist) | 5.7.76 | jsdelivr.net |
punycode | Production (bundled in dist) | 2.1.1 | deno.land/x |
jose | Production (bundled in dist) | 4.7.0 | deno.land/x |
cbor-x | Production (bundled in dist) | 1.2.1 | deno.land/x |
pkijs | Production (bundled in dist) | 2.1.58 | unpkg.com |
asn1js | Production (bundled in dist) | 2.3.2 | unpkg.com |
@hexagon/base64 | Production (bundled) | 1.0.18 | (bundled) |
std | Production (bundled in dist) / Testing | 0.134.0 | deno.land/std |
klon | Testing | 0.11.0 | esm.run |
Contributors
The underlying code is heavily based on github.com/webauthn-open-source/fido2-lib
License
MIT