From 683e165a60f12c5471c3a95709bfbcdbfa1a9151 Mon Sep 17 00:00:00 2001 From: Lucas Garron Date: Fri, 1 Aug 2025 12:21:02 -0700 Subject: [PATCH 1/6] Update deprecation notice. --- README.md | 45 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fa3fc9d6..ae8ae3f0 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,47 @@ -⚠️ ⚠️ ⚠️ +# ⚠️ `@github/webauthn-json` is deprecated -WebAuthn-json has been sunset. Now that [all major browsers support WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API#browser_compatibility) we recommend invoking the native APIs +As of March 2025, stable versions of all major browsers now support the following methods: -⚠️ ⚠️ ⚠️ +- [`PublicKeyCredential.parseCreationOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) +- [`PublicKeyCredential.parseRequestOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) + +By design, these are compatible with `@github/webauthn-json` encoding, so you can use them as a drop-in substitute. We strongly recommend doing so, since: + +- The browser-native JSON parsing functions are increasingly receiving fields and features (such as user-agent hints and the `prf` extension) that `@github/webauthn-json` will never receive. +- Removing `@github/webauthn-json` from your codebase will remove code from your authentication pages, reducing load times for your users and reducing the chance you will need to debug issues. + +If you need to support older browsers in the short-term, consider loading this library only as a fallback: + +```js +async function register() { + const parseCreationOptionsFromJSON = + PublicKeyCredential.parseCreationOptionsFromJSON ?? + /* @type PublicKeyCredential.parseCreationOptionsFromJSON */ + (await import("@github/webauthn-json/browser-ponyfill")).parseCreationOptionsFromJSON; + + const publicKey = parseCreationOptionsFromJSON({ /* … */ }); + return navigator.credentials.create({publicKey}); +} + +async function authenticate() { + const parseRequestOptionsFromJSON = + PublicKeyCredential.parseRequestOptionsFromJSON ?? + /* @type PublicKeyCredential.parseRequestOptionsFromJSON */ + (await import("@github/webauthn-json/browser-ponyfill")).parseRequestOptionsFromJSON; + + const publicKey = parseRequestOptionsFromJSON({ /* … */ }); + return navigator.credentials.get({publicKey}); +} +``` + +
+
+ +This project's old README contents are below: + +
+ +-------- # `@github/webauthn-json` From 9d194acf2ce46984bae7ff688d385269915119fa Mon Sep 17 00:00:00 2001 From: Lucas Garron Date: Wed, 6 Aug 2025 20:14:17 -0700 Subject: [PATCH 2/6] Provide an explicit example so that copying the first visible snippet is the "right" choice. --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index ae8ae3f0..b577d163 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,81 @@ -# ⚠️ `@github/webauthn-json` is deprecated +# ⚠️ `@github/webauthn-json` is deprecated ⚠️ As of March 2025, stable versions of all major browsers now support the following methods: - [`PublicKeyCredential.parseCreationOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) - [`PublicKeyCredential.parseRequestOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) -By design, these are compatible with `@github/webauthn-json` encoding, so you can use them as a drop-in substitute. We strongly recommend doing so, since: +These should be used instead of `@github/webauthn-json`. + +## 👉 Use built-in browser methods instead 👈 + +Here is an example for how to serialize and deserialize JSON for WebAuthn client code without using `@github/webauthn-json`: + +```ts +// Example in TypeScript + +const jsonWebAuthnSupport = !!globalThis.PublicKeyCredential?.parseCreationOptionsFromJSON; + +async function register() { + const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON({ /* … */ }); + const credential = (await navigator.credentials.create({publicKey})) as PublicKeyCredential; + return credential.toJSON(); +} + +async function authenticate() { + const publicKey = PublicKeyCredential.parseRequestOptionsFromJSON({ /* … */ }); + const credential = (await navigator.credentials.get({publicKey})) as PublicKeyCredential; + return credential.toJSON(); +} + +if (jsonWebAuthnSupport) { + /* Set up code to call `register()` and `authenticate()`. */ +} +``` + +## Reasoning + +`@github/webauthn-json` served as an ecosystem prototype of the functionality was [developed into the built-in browser methods](https://github.com/w3c/webauthn/wiki/Explainer:-JSON-Serialization-Methods). The built-in methods are compatible with `@github/webauthn-json` encoding, so you can use them as a drop-in substitute. We strongly recommend doing so, since: - The browser-native JSON parsing functions are increasingly receiving fields and features (such as user-agent hints and the `prf` extension) that `@github/webauthn-json` will never receive. - Removing `@github/webauthn-json` from your codebase will remove code from your authentication pages, reducing load times for your users and reducing the chance you will need to debug issues. +## Fallback (not recommended) + If you need to support older browsers in the short-term, consider loading this library only as a fallback: -```js +```ts +// Example in TypeScript + async function register() { - const parseCreationOptionsFromJSON = - PublicKeyCredential.parseCreationOptionsFromJSON ?? - /* @type PublicKeyCredential.parseCreationOptionsFromJSON */ - (await import("@github/webauthn-json/browser-ponyfill")).parseCreationOptionsFromJSON; + const parseCreationOptionsFromJSON: typeof PublicKeyCredential.parseCreationOptionsFromJSON = + PublicKeyCredential.parseCreationOptionsFromJSON ?? + (await import("@github/webauthn-json/browser-ponyfill")).parseCreationOptionsFromJSON; const publicKey = parseCreationOptionsFromJSON({ /* … */ }); - return navigator.credentials.create({publicKey}); + const credential = (await navigator.credentials.create({publicKey})) as PublicKeyCredential; + return credential.toJSON(); } async function authenticate() { - const parseRequestOptionsFromJSON = + const parseRequestOptionsFromJSON: typeof PublicKeyCredential.parseRequestOptionsFromJSON = PublicKeyCredential.parseRequestOptionsFromJSON ?? - /* @type PublicKeyCredential.parseRequestOptionsFromJSON */ (await import("@github/webauthn-json/browser-ponyfill")).parseRequestOptionsFromJSON; const publicKey = parseRequestOptionsFromJSON({ /* … */ }); - return navigator.credentials.get({publicKey}); + const credential = (await navigator.credentials.get({publicKey})) as PublicKeyCredential; + return credential.toJSON(); } ``` +If you think you need such a fallback, consider testing or instrumenting your code to test if this is really needed for the small percentage of affected users. + +If you have any other authentication methods available, it is likely that your users will still be able to authenticate without this fallback in place. They will also receive the browser-native functionality the next time their browser updates. +
+ +-------- +
This project's old README contents are below: @@ -43,6 +84,8 @@ This project's old README contents are below: -------- +
+ # `@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). From f66edaa33372e93acd354ce58e1a3a395d804378 Mon Sep 17 00:00:00 2001 From: Lucas Garron Date: Wed, 6 Aug 2025 20:22:53 -0700 Subject: [PATCH 3/6] Mention `.toJSON()`. Technically the syntax for referring to an instance method is `PublicKeyCredential#toJSON()` but I think this is problematic. So I've avoided it. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index b577d163..8155a36d 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ As of March 2025, stable versions of all major browsers now support the followin - [`PublicKeyCredential.parseCreationOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) - [`PublicKeyCredential.parseRequestOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) +- [`PublicKeyCredential` → `.toJSON()`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential) These should be used instead of `@github/webauthn-json`. From 88f0e8a43f156606a5a848eaed696330bdce8ff4 Mon Sep 17 00:00:00 2001 From: Lucas Garron Date: Wed, 6 Aug 2025 20:26:40 -0700 Subject: [PATCH 4/6] Update reasoning. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8155a36d..697a5e97 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,8 @@ if (jsonWebAuthnSupport) { `@github/webauthn-json` served as an ecosystem prototype of the functionality was [developed into the built-in browser methods](https://github.com/w3c/webauthn/wiki/Explainer:-JSON-Serialization-Methods). The built-in methods are compatible with `@github/webauthn-json` encoding, so you can use them as a drop-in substitute. We strongly recommend doing so, since: -- The browser-native JSON parsing functions are increasingly receiving fields and features (such as user-agent hints and the `prf` extension) that `@github/webauthn-json` will never receive. +- The browser-native JSON parsing functions are already available for the vast majority of users. +- They are increasingly receiving fields and features (such as user-agent hints and the `prf` extension) that `@github/webauthn-json` will never receive. - Removing `@github/webauthn-json` from your codebase will remove code from your authentication pages, reducing load times for your users and reducing the chance you will need to debug issues. ## Fallback (not recommended) From cd06c2b74eebc6a62af0b9b5b782b763bc3982c3 Mon Sep 17 00:00:00 2001 From: Lucas Garron Date: Fri, 8 Aug 2025 09:12:14 -0700 Subject: [PATCH 5/6] Update MDN links. Co-authored-by: Kevin Jones --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 697a5e97..c0aaf02a 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ As of March 2025, stable versions of all major browsers now support the following methods: -- [`PublicKeyCredential.parseCreationOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) -- [`PublicKeyCredential.parseRequestOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) -- [`PublicKeyCredential` → `.toJSON()`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential) +- [`PublicKeyCredential.parseCreationOptionsFromJSON(…)`](https://developer.mozilla.org/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) +- [`PublicKeyCredential.parseRequestOptionsFromJSON(…)`](https://developer.mozilla.org/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static) +- [`PublicKeyCredential` → `.toJSON()`](https://developer.mozilla.org/docs/Web/API/PublicKeyCredential) These should be used instead of `@github/webauthn-json`. From 72678107cc679253826c9f7fa706d49861981422 Mon Sep 17 00:00:00 2001 From: Lucas Garron Date: Fri, 8 Aug 2025 09:13:35 -0700 Subject: [PATCH 6/6] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c0aaf02a..11b52aa9 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ if (jsonWebAuthnSupport) { ## Reasoning -`@github/webauthn-json` served as an ecosystem prototype of the functionality was [developed into the built-in browser methods](https://github.com/w3c/webauthn/wiki/Explainer:-JSON-Serialization-Methods). The built-in methods are compatible with `@github/webauthn-json` encoding, so you can use them as a drop-in substitute. We strongly recommend doing so, since: +`@github/webauthn-json` served as an ecosystem prototype of the functionality that was [developed into the built-in browser methods](https://github.com/w3c/webauthn/wiki/Explainer:-JSON-Serialization-Methods). The built-in methods are compatible with `@github/webauthn-json` encoding, so you can use them as a drop-in substitute. We strongly recommend doing so, since: - The browser-native JSON parsing functions are already available for the vast majority of users. - They are increasingly receiving fields and features (such as user-agent hints and the `prf` extension) that `@github/webauthn-json` will never receive.