# @corbado/webauthn-json

> A wrapper for the webauthn API that adapts input/output values to plain JSON with base64url (Corbado fork)

Latest version **2.2.0** (published 2025-03-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install @corbado/webauthn-json
pnpm add @corbado/webauthn-json
yarn add @corbado/webauthn-json
bun add @corbado/webauthn-json
```

Provides the command `webauthn-json`.

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2025-03-31 |
| First published | 2024-10-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 295.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 786 |
| Author | GitHub, Inc. |
| Maintainers | vdelitz, stefan.becker, incorbador, dopeamin-corbado, lukaskratzel |
| Keywords | webauthn, auth, u2f, security, credentials |

## Links

- npm: https://www.npmjs.com/package/@corbado/webauthn-json
- Repository: https://github.com/github/webauthn-json
- Homepage: https://github.com/github/webauthn-json#readme
- Issues: https://github.com/github/webauthn-json/issues
- npm.io page: https://npm.io/package/@corbado/webauthn-json

## Alternatives

- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads
- [escher-request](https://npm.io/package/escher-request.md) — 545 weekly downloads

## Recent versions

- 2.2.0 (latest) — 2025-03-31
- 2.1.2 — 2024-10-11

## README

# `@github/webauthn-json`

`@github/webauthn-json` is a client-side Javascript library that serves as convenience wrapper for the the [WebAuthn API](https://www.w3.org/TR/webauthn/) by encoding binary data using [base64url](https://w3c.github.io/webauthn/#sctn-dependencies) (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](https://w3c.github.io/webauthn/#sctn-parseCreationOptionsFromJSON) some day, but we're here for you until then.

## Usage

1. Replace calls:
  - `navigator.credentials.create(...)` with `create(parseCreationOptionsFromJSON(...))`.
  - `navigator.credentials.get(...)` with `get(parseRequestOptionsFromJSON(...))`.
2. Encode/decode binary values on the server as base64url.

### Example

Install using:

```shell
npm install --save @github/webauthn-json
```

Then:

```typescript
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](https://github.com/github/webauthn-json/blob/main/src/dev/demo/index.ts) for fully working client-side [demo](https://github.github.com/webauthn-json/demo/) code.

### API (browser ponyfill)

We now recommend using a [ponyfill](https://ponyfill.com/) for the [new JSON-based APIs](https://github.com/w3c/webauthn/issues/1683) in the WebAuthn spec:

```typescript
// @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>;
```

### API (main library)

This was the original simplified API, which remains supported.

```typescript
// @github/webauthn-json

function create(requestJSON: JSON): Promise<JSON>;
function get(requestJSON: JSON): Promise<JSON>;
function supported(): boolean;
```

## Schema

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](https://github.com/github/webauthn-json/blob/main/src/webauthn-json/schema-format.ts). `@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:

```shell
npx @github/webauthn-json schema
```

## Extensions

Modern browsers generally only support — and most sites only need to use — a small number of [extensions](https://w3c.github.io/webauthn/#sctn-defined-extensions). To save code size, `@github/webauthn-json` only includes the following extensions by default:

- [`appid`](https://w3c.github.io/webauthn/#sctn-appid-extension)
- [`appidExclude`](https://w3c.github.io/webauthn/#sctn-appid-exclude-extension)
- [`credProps`](https://w3c.github.io/webauthn/#sctn-authenticator-credential-properties-extension)

In addition, we handle the following info (that is not technically part of extensions):

- [`transports`](https://w3c.github.io/webauthn/#dom-authenticatorattestationresponse-transports-slot) (on `AuthenticatorAttestationResponse`)[^1]

[^1]: This comes from `getTransports()` on the `AuthenticatorAttestationResponse`. Note that we don't include its three sibling functions (`getAuthenticatorData()`, `getPublicKey()`, and `getPublicKeyAlgorithm()`), since they duplicates information that is available in other parts of the response. In particular, the authenticator data is available inside the signed [attestation object](https://w3c.github.io/webauthn/#attestation-object).


If you need to convert additional input or output extensions, use either of the following:

- `createExtended()` and `getExtended()` from `@github/webauthn-json/extended`.
- `parseExtendedCreationOptionsFromJSON()` and `parseExtendedRequestOptionsFromJSON()` from `@github/webauthn-json/browser-ponyfill/extended`.

## Contributions

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!

---
_Source: https://npm.io/package/@corbado/webauthn-json · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._