{"id":13649252,"url":"https://github.com/github/webauthn-json","last_synced_at":"2025-05-14T12:08:26.084Z","repository":{"id":37502674,"uuid":"194727402","full_name":"github/webauthn-json","owner":"github","description":"🔏 A small WebAuthn API wrapper that translates to/from pure JSON using base64url.","archived":false,"fork":false,"pushed_at":"2024-09-01T14:13:33.000Z","size":1373,"stargazers_count":781,"open_issues_count":11,"forks_count":60,"subscribers_count":305,"default_branch":"main","last_synced_at":"2025-04-02T00:19:27.913Z","etag":null,"topics":["fido","fido2","security-key","u2f","webauthn","webauthn-library"],"latest_commit_sha":null,"homepage":"https://github.github.com/webauthn-json/demo/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-01T18:52:54.000Z","updated_at":"2025-03-31T06:55:48.000Z","dependencies_parsed_at":"2024-04-03T00:41:23.131Z","dependency_job_id":"2ccf7e7a-113b-4ec3-b2f7-5acd91d8581f","html_url":"https://github.com/github/webauthn-json","commit_stats":{"total_commits":268,"total_committers":11,"mean_commits":"24.363636363636363","dds":0.09328358208955223,"last_synced_commit":"63958abfcf04d1e56e3d054d9a156d1cfb3d3ee0"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fwebauthn-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fwebauthn-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fwebauthn-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fwebauthn-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/webauthn-json/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247954290,"owners_count":21024194,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fido","fido2","security-key","u2f","webauthn","webauthn-library"],"created_at":"2024-08-02T01:04:53.077Z","updated_at":"2025-04-09T01:24:13.431Z","avatar_url":"https://github.com/github.png","language":"TypeScript","readme":"# `@github/webauthn-json`\n\n`@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).\n\nThe 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.\n\n## Usage\n\n1. Replace calls:\n  - `navigator.credentials.create(...)` with `create(parseCreationOptionsFromJSON(...))`.\n  - `navigator.credentials.get(...)` with `get(parseRequestOptionsFromJSON(...))`.\n2. Encode/decode binary values on the server as base64url.\n\n### Example\n\nInstall using:\n\n```shell\nnpm install --save @github/webauthn-json\n```\n\nThen:\n\n```typescript\nimport {\n  create,\n  parseCreationOptionsFromJSON,\n} from \"@github/webauthn-json/browser-ponyfill\";\n\nconst request = fetch(\"...\");\n\nasync function createCredential() {\n  const json = await (await request).json();\n  const options = parseCreationOptionsFromJSON(json);\n  const response = await create(options);\n  fetch(\"...\", {\n    method: \"POST\",\n    body: JSON.stringify(response),\n  });\n}\n```\n\nSee [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.\n\n### API (browser ponyfill)\n\nWe 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:\n\n```typescript\n// @github/webauthn-json/browser-ponyfill\n\nfunction supported(): boolean;\n\nfunction parseCreationOptionsFromJSON(json: JSON): CredentialCreationOptions;\nfunction parseRequestOptionsFromJSON(json: JSON): CredentialRequestOptions;\n\n// You can call `.toJSON()` on the result or pass directly to `JSON.stringify()`.\nfunction create(options: CredentialCreationOptions): Promise\u003cPublicKeyCredential\u003e;\n// You can call `.toJSON()` on the result or pass directly to `JSON.stringify()`.\nfunction get(options: CredentialRequestOptions): Promise\u003cPublicKeyCredential\u003e;\n```\n\n### API (main library)\n\nThis was the original simplified API, which remains supported.\n\n```typescript\n// @github/webauthn-json\n\nfunction create(requestJSON: JSON): Promise\u003cJSON\u003e;\nfunction get(requestJSON: JSON): Promise\u003cJSON\u003e;\nfunction supported(): boolean;\n```\n\n## Schema\n\nThere 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).\n\nRight 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.\n\nTo print the current schema, run:\n\n```shell\nnpx @github/webauthn-json schema\n```\n\n## Extensions\n\nModern 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:\n\n- [`appid`](https://w3c.github.io/webauthn/#sctn-appid-extension)\n- [`appidExclude`](https://w3c.github.io/webauthn/#sctn-appid-exclude-extension)\n- [`credProps`](https://w3c.github.io/webauthn/#sctn-authenticator-credential-properties-extension)\n\nIn addition, we handle the following info (that is not technically part of extensions):\n\n- [`transports`](https://w3c.github.io/webauthn/#dom-authenticatorattestationresponse-transports-slot) (on `AuthenticatorAttestationResponse`)[^1]\n\n[^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).\n\n\nIf you need to convert additional input or output extensions, use either of the following:\n\n- `createExtended()` and `getExtended()` from `@github/webauthn-json/extended`.\n- `parseExtendedCreationOptionsFromJSON()` and `parseExtendedRequestOptionsFromJSON()` from `@github/webauthn-json/browser-ponyfill/extended`.\n\n## Contributions\n\nThe 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!\n","funding_links":[],"categories":["Library","TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fwebauthn-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fwebauthn-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fwebauthn-json/lists"}