Registry / auth-security / u2f-api

u2f-api

JSON →
library1.2.1jsnpmunverified

u2f-api is a client-side JavaScript library that provides a promisified interface for interacting with the Universal 2nd Factor (U2F) API in web browsers. It aims to abstract away browser-specific implementations of U2F, offering support for Chrome (including its historical extension methods), Opera, and Firefox 58+ (though with some caveats regarding multi-domain registrations). The library provides core functions such as `register()` and `sign()` for managing U2F security keys, alongside `isSupported()` and `ensureSupport()` for client capability detection. The current stable version is 1.2.1, released in January 2021. Its release cadence is infrequent, suggesting a maintenance-only status. A key differentiator is its modern Promise-based API and its efforts to normalize U2F interactions across different browsers, but it's crucial to understand that U2F itself is largely a legacy standard, with WebAuthn being the modern successor for FIDO authentication. This library requires a complementary server-side implementation (e.g., using the `u2f` npm package) to function fully.

npm install u2f-api
INSTALL
IMPORT
SIG · U2F-API
U
u2f-api
auth-securityjavascriptv1.2.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

register
import { register } from 'u2f-api'
const register = require('u2f-api').register
Primary function for initiating a U2F registration ceremony. This library ships TypeScript types.
sign
import { sign } from 'u2f-api'
const sign = require('u2f-api').sign
Primary function for initiating a U2F authentication (signing) ceremony. This library ships TypeScript types.
isSupported
import { isSupported } from 'u2f-api'
const isSupported = require('u2f-api').isSupported
Asynchronously checks if the client browser supports U2F, returning a Promise<boolean>.
u2fApi
import u2fApi from 'u2f-api'
import { u2fApi } from 'u2f-api'
When using the library without a bundler via a script tag, the functionality is exposed on `window.u2fApi`. CommonJS `require('u2f-api')` also returns an object containing all functions.

Demonstrates a full client-side U2F workflow, including checking for browser support, initiating a registration ceremony, and performing a sign-in (authentication) using mock server responses.

import { isSupported, register, sign } from 'u2f-api'; // Simulate server-side components const simulateServer = { async getRegistrationRequests() { // In a real app, this would fetch from your backend U2F server console.log('Server: Generating registration requests...'); return [{ version: 'U2F_V2', challenge: 'challenge-reg-1', appId: 'https://example.com' }]; }, async getSignRequests() { // In a real app, this would fetch from your backend U2F server console.log('Server: Generating sign requests...'); const registeredKeyHandle = 'mock-key-handle'; // From a previously registered key return [{ version: 'U2F_V2', challenge: 'challenge-sign-1', appId: 'https://example.com', keyHandle: registeredKeyHandle }]; }, async sendRegistrationResponse(response) { console.log('Server: Received registration response:', response); // In a real app, verify response and store key data return { success: true, message: 'Registration successful!' }; }, async sendSignResponse(response) { console.log('Server: Received sign response:', response); // In a real app, verify response against stored key data return { success: true, message: 'Authentication successful!' }; }, }; async function runU2FWorkflow() { try { const supported = await isSupported(); if (!supported) { console.warn('U2F is not supported in this browser or environment. Consider WebAuthn.'); return; } console.log('U2F is supported!'); // 1. Initiate Registration console.log('\n--- Initiating U2F Registration ---'); const regRequests = await simulateServer.getRegistrationRequests(); const registrationResponse = await register(regRequests); console.log('Client: U2F Register Response:', registrationResponse); await simulateServer.sendRegistrationResponse(registrationResponse); console.log('Registration workflow complete.'); // 2. Initiate Sign-in (Authentication) console.log('\n--- Initiating U2F Sign-in ---'); const signRequests = await simulateServer.getSignRequests(); const signResponse = await sign(signRequests); console.log('Client: U2F Sign Response:', signResponse); await simulateServer.sendSignResponse(signResponse); console.log('Sign-in workflow complete.'); } catch (error: any) { console.error('U2F Workflow Error:', error.message); if (error.metaData) { console.error('U2F Error Code:', error.metaData.code, 'Type:', error.metaData.type); } } } runU2FWorkflow();
Debug
Known issues
breakingAs of v1.0.0, support for custom Promise libraries was removed, and Promises are no longer cancellable. The library now exclusively uses native browser Promises.
fix
Ensure your application relies on native Promises or polyfills them globally if targeting older environments. Remove any custom Promise injections.
affects: >=1.0.0
gotchaU2F (Universal 2nd Factor) is largely considered a legacy standard, and its functionality has been superseded by WebAuthn (FIDO2) which offers broader support, more features (e.g., passwordless login), and improved security. Modern applications should prioritize WebAuthn where possible.
fix
For new implementations, investigate FIDO2/WebAuthn libraries (e.g., `fido2-lib` for server-side) instead of U2F. Consider a phased migration strategy for existing U2F users to WebAuthn.
affects: >=0.1.0
gotchaBrowser support for U2F is inconsistent. While Chrome and Opera have some compatibility (historically via extensions), and Firefox 58+ offers partial support, Safari and other browsers still lack direct U2F functionality. Multi-domain registrations may behave differently across supported browsers.
fix
Always use `isSupported()` or `ensureSupport()` before attempting U2F operations. Provide fallback authentication methods or inform users about browser compatibility requirements.
affects: >=0.1.0
gotchaThis library is purely client-side. A complete U2F authentication system requires a robust server-side component to generate challenges, verify responses, and manage key registrations. Without a server-side counterpart, this client library cannot facilitate secure U2F.
fix
Integrate with a server-side U2F library (e.g., the `u2f` npm package) to handle cryptographic challenge generation and response verification. Ensure secure communication between client and server.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Timeout
The user did not interact with the U2F security key (e.g., press the button) within the specified timeout period, or the U2F device was unresponsive.
fix
Increase the `timeout` parameter in `register()` or `sign()` calls (specified in seconds). Advise users to quickly interact with their security key when prompted. Ensure the U2F device is properly connected and functioning.
Error: Device Ineligible
The U2F device is not eligible for the requested operation, possibly due to a previously registered key handle not matching or other device-specific issues.
fix
Verify that the `signRequests` array contains correct and current key handles associated with the user. Ensure the user is presenting the correct U2F device. This error can also occur if the device has an internal error.
ReferenceError: u2fApi is not defined
This typically happens when trying to use `u2fApi` as a global variable (e.g., after including `bundle.js`) but the script hasn't loaded, or when using ES Modules/CommonJS without proper import.
fix
If using a script tag, ensure `bundle.js` is loaded before your application code, and access methods via `window.u2fApi`. If using a bundler, ensure you have `import u2fApi from 'u2f-api'` or specific named imports like `import { register } from 'u2f-api'`.
Upgrade
Version history
1.2.1latest on npm
Audit
Dependencies
u2frequiredProvides complementary server-side functionality for U2F registration and signing, which is essential for a complete U2F authentication flow.
Agent activity
32 hits · last 30 days
node
26
OpenAI (training)
1
Resources