fix: detect WebAuthn extensions by asking the browser (#9)

checkExtensionSupport() tested `'largeBlob' in PublicKeyCredential.prototype`.
Extensions are never properties of that interface — they arrive through
getClientExtensionResults() — so the test answered false in every browser ever
shipped, including ones with complete support. hmacSecret sat beside it
hard-coded to false. Together they meant the encrypted-keystore demo disabled
its own headline feature everywhere, and the checkbox could not be ticked at
all.

Measured on Chrome 148 rather than assumed: the prototype probe returns false
for largeBlob, prf and hmacCreateSecret, while getClientCapabilities() on the
same page reports all three true. Probing appid, credBlob and credProps the
same way also returns false, so this was never a vendor quirk — the question
was asked of the wrong object.

Worth naming what this means for #9. The crash it reported ("No hmac-secret
output from credential") did stop happening, but not because anything was
fixed: the path became unreachable when the detection started answering false
everywhere, which also took the working paths with it. The feature was quiet,
not well.

Now:

- checkExtensionSupport() reads getClientCapabilities(), reports prf alongside
  largeBlob and hmacSecret, and returns `known` so callers can tell "the
  browser says no" from "the browser cannot say". Treating the second as a
  refusal is how a working feature gets disabled.
- extensionSupportFromCredential() reads what the authenticator actually agreed
  to, from the registration response. Client support is not authenticator
  support; only the ceremony settles it, and the answer belongs to the
  credential.
- addLargeBlobToCredentialOptions() takes a support level, still 'required' by
  default — under 'preferred' an unsupported authenticator yields a credential
  whose secret was never written, which loses the keystore silently.
- The demo offers PRF and prefers it, matching the library default since 0.4.0.
  It had hard-coded largeBlob and so never exercised PRF.

Tests: 12 new cases, including the old prototype probe kept as a regression
guard. 57 node tests pass, format and lint clean, the demo builds.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: NiKrause

CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## Unreleased
 
+### Fixed
+
+- Detect WebAuthn extensions by asking the browser instead of inspecting a
+  prototype. `checkExtensionSupport()` tested
+  `'largeBlob' in PublicKeyCredential.prototype` — but extensions are never
+  properties of that interface, they arrive through
+  `getClientExtensionResults()`. The test therefore returned `false` in every
+  browser ever shipped, including those with complete support, and `hmacSecret`
+  was hard-coded `false` beside it. Both together meant the encrypted-keystore
+  demo disabled its own headline feature everywhere and could not be switched
+  on at all.
+
+  Measured on Chrome 148: the prototype probe answered `false` for `largeBlob`,
+  `prf` and `hmacCreateSecret` while `getClientCapabilities()` reported all
+  three `true`. Every extension name behaves the same way, so no browser could
+  ever have passed. Closes #9.
+
+  `checkExtensionSupport()` now reads `getClientCapabilities()` and reports
+  `prf` alongside the other two. It also returns `known`, distinguishing "the
+  browser says no" from "the browser cannot say" — callers must not treat the
+  second as a refusal, or they disable a feature that may well work.
+
+### Added
+
+- `extensionSupportFromCredential(credential)` reads what the authenticator
+  actually agreed to, from the registration response. This is the authoritative
+  answer and the one worth persisting: a browser may support `largeBlob` while
+  the security key in front of it does not, and only the ceremony settles that.
+  `addLargeBlobToCredentialOptions()` takes an optional support level for the
+  same reason — it stays `'required'` by default, because under `'preferred'`
+  an unsupported authenticator yields a credential whose secret was silently
+  never written.
+
+### Changed
+
+- The encrypted-keystore demo offers PRF as a keystore encryption method and
+  prefers it, matching the library's own default since 0.4.0. It had hard-coded
+  `largeBlob`, so it overrode that default and never exercised PRF at all.
+  Methods the browser cannot vouch for are now labelled "Unknown" rather than
+  "Not supported", and stay selectable.
+
 ## 0.5.0
 
 ### Breaking

examples/ed25519-encrypted-keystore-demo/src/lib/WebAuthnTodo.svelte

@@ -53,10 +53,17 @@
 
   // NEW: Encryption options
   let useEncryption = true; // Enable encryption by default
-  let encryptionMethod = 'largeBlob'; // or 'hmac-secret'
+  let encryptionMethod = 'prf'; // 'prf', 'largeBlob' or 'hmac-secret'
   let useKeystoreDID = true; // Use persistent DID from OrbitDB keystore (instead of WebAuthn P-256)
   let keystoreKeyType = 'Ed25519'; // Key type: 'secp256k1' or 'Ed25519' (default: Ed25519)
-  let extensionSupport = { largeBlob: false, hmacSecret: false };
+  // `known: false` means the browser could not tell us, which is not the same
+  // as "unsupported" — see checkEncryptionSupport().
+  let extensionSupport = {
+    prf: false,
+    largeBlob: false,
+    hmacSecret: false,
+    known: false,
+  };
   let useWorkerKeystore = false;
   let workerAvailable = false;
   let workerClient = null;
@@ -149,19 +156,38 @@
     resetWorkerClient();
   });
 
+  // Three states, not two: an extension we know is missing reads differently
+  // from one the browser would not tell us about.
+  function supportLabel(flag) {
+    if (flag) return '✅ Supported';
+    return extensionSupport.known ? '❌ Not supported' : '❓ Unknown';
+  }
+
   async function checkEncryptionSupport() {
     try {
       extensionSupport = await KeystoreEncryption.checkExtensionSupport();
       console.log('Encryption extension support:', extensionSupport);
 
-      // Auto-select best encryption method
-      if (extensionSupport.largeBlob) {
+      // Auto-select best encryption method. PRF first: it is what the library
+      // itself defaults to, and it derives the key from the authenticator
+      // instead of storing a wrapped one.
+      if (extensionSupport.prf) {
+        encryptionMethod = 'prf';
+      } else if (extensionSupport.largeBlob) {
         encryptionMethod = 'largeBlob';
       } else if (extensionSupport.hmacSecret) {
         encryptionMethod = 'hmac-secret';
-      } else {
-        useEncryption = false; // Disable if no support
+      } else if (extensionSupport.known) {
+        useEncryption = false; // The browser told us it supports none of them.
         console.warn('No encryption extensions supported');
+      } else {
+        // The browser has no getClientCapabilities(), so it cannot say in
+        // advance. Attempting the ceremony is the only way to find out, and
+        // it is better than refusing a feature that may well work.
+        encryptionMethod = 'prf';
+        console.warn(
+          'Extension support could not be determined; attempting PRF anyway'
+        );
       }
     } catch (error) {
       console.error('Failed to check encryption support:', error);
@@ -852,7 +878,10 @@
                 type="checkbox"
                 bind:checked={useEncryption}
                 disabled={loading ||
-                  (!extensionSupport.largeBlob && !extensionSupport.hmacSecret)}
+                  (extensionSupport.known &&
+                    !extensionSupport.prf &&
+                    !extensionSupport.largeBlob &&
+                    !extensionSupport.hmacSecret)}
                 style="cursor: pointer;"
               />
               <span style="color: var(--cds-text-primary);"
@@ -899,23 +928,40 @@
                   style="font-size: 0.875rem; font-weight: 500; color: var(--cds-text-primary);"
                   >Encryption Method:</span
                 >
+                <label
+                  style="display: flex; align-items: center; gap: 0.5rem; cursor: pointer;"
+                >
+                  <input
+                    type="radio"
+                    bind:group={encryptionMethod}
+                    value="prf"
+                    disabled={loading ||
+                      (extensionSupport.known && !extensionSupport.prf)}
+                    style="cursor: pointer;"
+                  />
+                  <span style="color: var(--cds-text-primary);">PRF</span>
+                  <span
+                    style="font-size: 0.75rem; color: var(--cds-text-secondary);"
+                  >
+                    {supportLabel(extensionSupport.prf)}
+                  </span>
+                </label>
                 <label
                   style="display: flex; align-items: center; gap: 0.5rem; cursor: pointer;"
                 >
                   <input
                     type="radio"
                     bind:group={encryptionMethod}
                     value="largeBlob"
-                    disabled={loading || !extensionSupport.largeBlob}
+                    disabled={loading ||
+                      (extensionSupport.known && !extensionSupport.largeBlob)}
                     style="cursor: pointer;"
                   />
                   <span style="color: var(--cds-text-primary);">largeBlob</span>
                   <span
                     style="font-size: 0.75rem; color: var(--cds-text-secondary);"
                   >
-                    {extensionSupport.largeBlob
-                      ? '✅ Supported'
-                      : '❌ Not supported'}
+                    {supportLabel(extensionSupport.largeBlob)}
                   </span>
                 </label>
                 <label
@@ -925,7 +971,8 @@
                     type="radio"
                     bind:group={encryptionMethod}
                     value="hmac-secret"
-                    disabled={loading || !extensionSupport.hmacSecret}
+                    disabled={loading ||
+                      (extensionSupport.known && !extensionSupport.hmacSecret)}
                     style="cursor: pointer;"
                   />
                   <span style="color: var(--cds-text-primary);"
@@ -934,9 +981,7 @@
                   <span
                     style="font-size: 0.75rem; color: var(--cds-text-secondary);"
                   >
-                    {extensionSupport.hmacSecret
-                      ? '✅ Supported'
-                      : '❌ Not supported'}
+                    {supportLabel(extensionSupport.hmacSecret)}
                   </span>
                 </label>
               </div>

examples/ed25519-encrypted-keystore-demo/src/lib/libp2p.js

@@ -125,7 +125,7 @@ export async function createIdentitiesInstance() {
  * @param {boolean} options.useKeystoreDID - Use persistent DID from OrbitDB keystore (instead of WebAuthn P-256)
  * @param {string} options.keystoreKeyType - Key type: 'secp256k1' or 'Ed25519'
  * @param {boolean} options.encryptKeystore - Enable keystore encryption
- * @param {string} options.encryptionMethod - Encryption method ('largeBlob' or 'hmac-secret')
+ * @param {string} options.encryptionMethod - Encryption method ('prf', 'largeBlob' or 'hmac-secret')
  */
 export async function createWebAuthnIdentity(
   identities,
@@ -137,7 +137,9 @@ export async function createWebAuthnIdentity(
     useKeystoreDID = false,
     keystoreKeyType = 'secp256k1',
     encryptKeystore = false,
-    encryptionMethod = 'largeBlob',
+    // Matches the library's own default since 0.4.0. Hard-coding 'largeBlob'
+    // here meant the demo silently overrode it and never exercised PRF.
+    encryptionMethod = 'prf',
   } = options;
 
   return await identities.createIdentity({

playwright.node.config.js

@@ -18,6 +18,7 @@ export default defineConfig({
   testMatch: [
     'standalone-toolkit.test.js',
     'webauthn-debug-log.test.js',
+    'webauthn-extension-support.test.js',
     'webauthn-varsig-challenge.test.js',
     'webauthn-attestation-parsing.test.js',
     'webauthn-two-peer-replication.test.js',

src/index.js

@@ -287,6 +287,7 @@ export {
   loadEncryptedKeystore,
   clearEncryptedKeystore,
   checkExtensionSupport,
+  extensionSupportFromCredential,
 } from './keystore/encryption.js';
 
 export default {

src/keystore/encryption.js

@@ -150,19 +150,37 @@ export async function decryptWithAESGCM(ciphertext, sk, iv) {
 
 /**
  * Store secret key in WebAuthn credential using largeBlob extension
+ *
+ * Defaults to `support: 'required'` so an authenticator that cannot hold a
+ * blob fails the ceremony outright. That is the safe default here: under
+ * `'preferred'` the credential is created successfully and the secret is
+ * simply never written, which loses the keystore silently.
+ *
+ * Pass `'preferred'` only when the caller reads the outcome back with
+ * {@link extensionSupportFromCredential} and handles an unsupported
+ * authenticator itself — probing for capability, for instance.
+ *
  * @param {Object} credentialOptions - WebAuthn credential creation options
  * @param {Uint8Array} sk - Secret key to store
- * @returns {Promise<Object>} Enhanced credential options with largeBlob
+ * @param {'required'|'preferred'} [support] - largeBlob support level
+ * @returns {Object} Enhanced credential options with largeBlob
  */
-export function addLargeBlobToCredentialOptions(credentialOptions, sk) {
-  log('Adding largeBlob extension to credential options');
+export function addLargeBlobToCredentialOptions(
+  credentialOptions,
+  sk,
+  support = 'required'
+) {
+  log(
+    'Adding largeBlob extension to credential options (support: %s)',
+    support
+  );
 
   return {
     ...credentialOptions,
     extensions: {
       ...credentialOptions.extensions,
       largeBlob: {
-        support: 'required',
+        support,
         write: sk,
       },
     },
@@ -620,39 +638,95 @@ export async function clearEncryptedKeystore(credentialId) {
 }
 
 /**
- * Check if browser supports WebAuthn extensions
- * @returns {Promise<Object>} Support status for largeBlob and hmac-secret
+ * Which WebAuthn extensions is this *client* willing to negotiate?
+ *
+ * Answers one question only: would the browser pass the extension through. It
+ * cannot tell you whether the authenticator behind it will honour the request —
+ * that is settled during a ceremony, by
+ * {@link extensionSupportFromCredential}, and belongs to the credential rather
+ * than to the browser.
+ *
+ * `known: false` means the browser is too old to say. That is **not** the same
+ * as unsupported: callers should attempt the ceremony and let its result
+ * decide, rather than disabling the feature outright.
+ *
+ * @returns {Promise<{largeBlob: boolean, prf: boolean, hmacSecret: boolean, known: boolean}>}
  */
 export async function checkExtensionSupport() {
   const support = {
     largeBlob: false,
+    prf: false,
     hmacSecret: false,
+    known: false,
   };
 
-  if (!window.PublicKeyCredential) {
+  if (typeof globalThis.PublicKeyCredential !== 'function') {
     return support;
   }
 
-  try {
-    // Check largeBlob support
-    if (
-      window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable
-    ) {
-      const available =
-        await window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
-      // largeBlob is available in Chrome 106+, Edge 106+
-      support.largeBlob =
-        available && 'largeBlob' in PublicKeyCredential.prototype;
-    }
+  // getClientCapabilities is the only pre-flight answer that means anything.
+  // The previous check asked `'largeBlob' in PublicKeyCredential.prototype`,
+  // which tests whether the extension is a property of the credential
+  // interface. Extensions never are — they arrive through
+  // getClientExtensionResults() — so it returned false in every browser ever
+  // shipped, including those with complete support, and silently disabled
+  // keystore encryption everywhere.
+  if (typeof PublicKeyCredential.getClientCapabilities !== 'function') {
+    log('getClientCapabilities unavailable; extension support is unknown');
+    return support;
+  }
 
-    // hmac-secret support cannot be reliably detected without a real credential.
-    // Keep it false by default and let users opt-in explicitly.
-    support.hmacSecret = false;
+  try {
+    const capabilities = await PublicKeyCredential.getClientCapabilities();
+    return {
+      largeBlob: capabilities['extension:largeBlob'] === true,
+      prf: capabilities['extension:prf'] === true,
+      hmacSecret: capabilities['extension:hmacCreateSecret'] === true,
+      known: true,
+    };
   } catch (error) {
     log.error('Failed to check extension support: %s', error.message);
+    return support;
+  }
+}
+
+/**
+ * What did the authenticator actually agree to, for this credential?
+ *
+ * The authoritative answer, and the only one worth persisting: a browser may
+ * support largeBlob while the security key in front of it does not. Read this
+ * from the registration response and store it next to the credential.
+ *
+ * Requires the ceremony to have asked with `support: 'preferred'` — see
+ * {@link addLargeBlobToCredentialOptions}. Asking with `'required'` makes
+ * creation fail outright instead of reporting back.
+ *
+ * @param {PublicKeyCredential} credential - The result of navigator.credentials.create().
+ * @returns {{largeBlob: boolean, prf: boolean, hmacSecret: boolean}}
+ */
+export function extensionSupportFromCredential(credential) {
+  const support = { largeBlob: false, prf: false, hmacSecret: false };
+
+  if (typeof credential?.getClientExtensionResults !== 'function') {
+    return support;
   }
 
-  return support;
+  try {
+    const results = credential.getClientExtensionResults() ?? {};
+    return {
+      largeBlob: results.largeBlob?.supported === true,
+      // PRF reports either an explicit `enabled` flag or, when the ceremony
+      // evaluated a salt straight away, the results themselves.
+      prf: results.prf?.enabled === true || results.prf?.results != null,
+      hmacSecret: results.hmacCreateSecret === true,
+    };
+  } catch (error) {
+    log.error(
+      'Failed to read extension results from credential: %s',
+      error.message
+    );
+    return support;
+  }
 }
 
 export default {
@@ -668,4 +742,5 @@ export default {
   loadEncryptedKeystore,
   clearEncryptedKeystore,
   checkExtensionSupport,
+  extensionSupportFromCredential,
 };