U2F API Polyfill

0.4.4 · maintenance · verified Tue Apr 21

The `u2f-api-polyfill` package provides a JavaScript polyfill that implements the high-level FIDO U2F (Universal 2nd Factor) API for web browsers. It specifically targets environments where `window.u2f` might not natively exist, such as older Chrome versions. Maintained as version 0.4.4, its release cadence is irregular, primarily serving to pull in updates from Google's authoritative `u2f-ref-code` repository. This package acts as a direct port of Google's reference implementation, simplifying its consumption via NPM and eliminating the need for manual synchronization. It is not an independent U2F implementation but a faithful reproduction of Google's code designed for browser compatibility and to expose the global `window.u2f` object. While U2F itself has largely been superseded by the more modern WebAuthn standard, this polyfill remains relevant for maintaining compatibility with existing U2F implementations and legacy applications.

Common errors

```
Uncaught ReferenceError: u2f is not defined
```
cause The `u2f-api-polyfill` script was either not loaded, failed to execute, or did not successfully polyfill `window.u2f` (e.g., due to an existing `window.u2f` object or browser incompatibility).

fix Ensure the `u2f-api-polyfill` script is correctly imported or included in your HTML before attempting to access `window.u2f`. Check the browser's console for any loading errors. Verify that the browser environment (e.g., Chrome) is one where the polyfill is expected to activate.

Warnings

breaking Version 0.4.2 removed the implicit dependency on jQuery. Applications that relied on jQuery being present in the global scope after importing this polyfill may experience errors. Ensure jQuery is explicitly loaded if still required.
Fix: If your application implicitly relied on jQuery being loaded by `u2f-api-polyfill`, ensure you include jQuery as a separate dependency and load it before `u2f-api-polyfill` if needed.
gotcha The FIDO U2F API, and thus this polyfill, is largely superseded by the WebAuthn API, which offers a more modern, flexible, and secure approach to strong authentication. New implementations should prefer WebAuthn.
Fix: For new applications, consider migrating to or implementing WebAuthn for FIDO authentication. This polyfill is primarily for maintaining compatibility with legacy U2F deployments.
gotcha This polyfill is designed to load only if `window.u2f` is undefined, typically in older Chrome environments. If another U2F implementation is already present or if the browser natively supports `window.u2f`, the polyfill might not activate or could potentially conflict.
Fix: Ensure that `u2f-api-polyfill` is loaded in an environment where `window.u2f` is genuinely absent and that no other U2F polyfills or scripts are conflicting. Test thoroughly across target browsers.
gotcha The polyfill primarily targets Chrome and older Edge versions, as indicated by its original scope. Compatibility with other browsers or very recent browser versions that have moved to WebAuthn may vary or be limited.
Fix: Verify compatibility with your specific target browser versions. For broader or modern browser support, rely on WebAuthn or a polyfill explicitly designed for it.

Install

npm install u2f-api-polyfill npm
yarn add u2f-api-polyfill yarn
pnpm add u2f-api-polyfill pnpm

Imports

window.u2f
wrong:
```
import { u2f } from 'u2f-api-polyfill';
```
correct:
```
import 'u2f-api-polyfill';
// Then, use the global object:
// window.u2f.register(...)
```
This package is a polyfill that modifies the global `window.u2f` object upon import or script execution. There are no named or default exports from the package itself. For CommonJS, use `require('u2f-api-polyfill');` for the same side-effect.

Quickstart

Demonstrates how to include the `u2f-api-polyfill` and then interact with the global `window.u2f` object for FIDO U2F registration. This code would typically run in a browser environment.

import 'u2f-api-polyfill';

const appId = 'https://your-domain.com'; // Replace with your application's origin
const registerRequests = [{
  version: 'U2F_V2',
  challenge: 'challenge_string_for_registration',
  appId: appId
}];
const signRequests = [{
  version: 'U2F_V2',
  challenge: 'challenge_string_for_authentication',
  appId: appId,
  keyHandle: 'base64_encoded_key_handle' // obtained during registration
}];

if (window.u2f) {
  console.log('U2F API is available.');

  // Example registration call
  window.u2f.register(
    registerRequests,
    [], // Sign requests (optional for registration)
    (response) => {
      if (response.errorCode) {
        console.error('U2F Registration Error:', response);
        return;
      }
      console.log('U2F Registration Success:', response);
      // Send response to your server for verification
    }
  );

  // Example sign call (after successful registration)
  // window.u2f.sign(
  //   signRequests,
  //   (response) => {
  //     if (response.errorCode) {
  //       console.error('U2F Sign Error:', response);
  //       return;
  //     }
  //     console.log('U2F Sign Success:', response);
  //     // Send response to your server for verification
  //   }
  // );
} else {
  console.warn('U2F API not available. This polyfill might not have loaded or browser does not support it.');
}

view raw JSON →