webauthn-json 2.0.0-alpha4
Install from the command line:
Learn more about npm packages
$ npm install @github/webauthn-json@2.0.0-alpha4
Install via package.json:
"@github/webauthn-json": "2.0.0-alpha4"
About this version
@github/webauthn-json
is a client-side Javascript library that serves as convenience wrapper for the the WebAuthn API by encoding binary data using base64url (also known as "websafe" or "urlsafe" base64).
The WebAuthn API itself takes input and output values that look almost like JSON, except that binary data is represented as ArrayBuffer
s. Using webauthn-json
allows the data to be sent from/to the server as normal JSON without any custom client-side processing. This will be possible directly in the browser some day, but we're here for you until then.
- Replace calls to
navigator.credentials.create()
withcreate()
, andnavigator.credentials.get()
withget()
. - Encode/decode binary values on the server as base64url.
Install using:
npm install --save @github/webauthn-json
Then:
import {
create,
parseCreationOptionsFromJSON,
} from "@github/webauthn-json/browser-ponyfill";
const request = fetch("...");
async function createCredential() {
const json = await (await request).json();
const options = parseCreationOptionsFromJSON(json);
const response = await create(options);
fetch("...", {
method: "POST",
body: JSON.stringify(response),
});
}
See here for fully working client-side demo code.
We now recommend using a ponyfill for the new JSON-based APIs in the WebAuthn spec:
// @github/webauthn-json/browser-ponyfill
function supported(): boolean;
function parseCreationOptionsFromJSON(json: JSON): CredentialCreationOptions;
function parseRequestOptionsFromJSON(json: JSON): CredentialRequestOptions;
// You can call `.toJSON()` on the result or pass directly to `JSON.stringify()`.
function create(
options: CredentialCreationOptions,
): Promise<PublicKeyCredential>;
// You can call `.toJSON()` on the result or pass directly to `JSON.stringify()`.
function get(options: CredentialRequestOptions): Promise<PublicKeyCredential>;
This was the original simplified API, which remains supported.
// @github/webauthn-json
function create(requestJSON: JSON): Promise<JSON>;
function get(requestJSON: JSON): Promise<JSON>;
function supported(): boolean;
There are are several ways to encode JSON with binary fields. @github/webauthn-json
focuses on one simple approach: converting the known structure using a simple (custom) schema format. @github/webauthn-json
uses a few tricks for a compact schema encoding: the main build is about ≈1KB when minified and gzipped (although we publish unminified builds).
Right now, we only convert fields explicitly known to be used by the WebAuthn API. This means that you'll have to update to a newer version of this library if you want to use new fields in the future.
To print the current schema, run:
npx @github/webauthn-json schema
Modern browsers generally only support — and most sites only need to use — a small number of extensions. To save code size, @github/webauthn-json
only includes the following extensions by default:
appid
appidExclude
credProps
In addition, we handle the following info (that is not technically part of extensions):
-
transports
(on a public key credential)
If you need to convert additional input or output extensions, use either of the following:
-
createExtended()
andgetExtended()
from@github/webauthn-json/extended
. -
parseExtendedCreationOptionsFromJSON()
andparseExtendedRequestOptionsFromJSON()
from@github/webauthn-json/browser-ponyfill/extended
.
The scope of @github/webauthn-json
is fairly small — it's essentially feature-complete. However, we're happy to accept issues or pull requests that address the core goal of the project!
Details
- webauthn-json
-
github
- about 2 years ago
- MIT
- 8 dependencies
Assets
- webauthn-json-2.0.0-alpha4.tgz
Download activity
- Total downloads 4
- Last 30 days 0
- Last week 0
- Today 0