U2F API for browsers
U2F has for a long time been supported in Chrome, although not with the standard window.u2f methods, but through a built-in extension. Nowadays, browsers seem to use window.u2f to expose the functionality.
Supported browsers are:
Safari and other browsers still lack U2F support.
Since 0.1.0, this library supports the standard window.u2f methods.
The library should be complemented with server-side functionality, e.g. using the u2f package.
u2f-api exports two main functions and an error "enum". The main functions are register() and sign(), although since U2F isn't widely supported, the functions isSupported() as well as ensureSupport() helps you build applications which can use U2F only when the client supports it.
import { isSupported } from 'u2f-api'
isSupported(): Promise< Boolean > // Doesn't throw/reject
import { ensureSupport } from 'u2f-api'
ensureSupport(): Promise< void > // Throws/rejects if not supported
import { register } from 'u2f-api'
register(
registerRequests: RegisterRequest[],
signRequests: SignRequest[], // optional
timeout: number // optional
): Promise< RegisterResponse >
The registerRequests can be either a RegisterRequest or an array of such. The optional signRequests must be, unless ignored, an array of SignRequests. The optional timeout is in seconds, and will default to an implementation specific value, e.g. 30.
import { sign } from 'u2f-api'
sign(
signRequests: SignRequest[],
timeout: number // optional
): Promise< SignResponse >
The values and interpretation of the arguments are the same as with register( ).
register() and sign() can return rejected promises. The rejection error is an Error object with a metaData property containing code and type. The code is a numerical value describing the type of the error, and type is the name of the error, as defined by the ErrorCodes enum in the "FIDO U2F Javascript API" specification. They are:
OK = 0 // u2f-api will never throw errors with this code
OTHER_ERROR = 1
BAD_REQUEST = 2
CONFIGURATION_UNSUPPORTED = 3
DEVICE_INELIGIBLE = 4
TIMEOUT = 5
The library is promisified and will use the built-in native promises of the browser, unless another promise library is injected (deprecated since 1.0).
var u2fApi = require( 'u2f-api' ); // CommonJS
import u2fApi from 'u2f-api' // ES modules
u2f-api can be used without a bundler (like Webpack). Just include:
<head><script src="https://cdn.jsdelivr.net/npm/u2f-api@latest/bundle.js"></script></head>
The functionality will be in the window.u2fApi object.
With registerRequestsFromServer somehow received from the server, the client code becomes:
u2fApi.register( registerRequestsFromServer )
.then( sendRegisterResponseToServer )
.catch( ... );
With signRequestsFromServer also received from the server somehow:
u2fApi.sign( signRequestsFromServer )
.then( sendSignResponseToServer )
.catch( ... );
u2fApi.isSupported( )
.then( function( supported ) {
if ( supported )
{
return u2fApi.sign( signRequestsFromServer )
.then( sendSignResponseToServer );
}
else
{
... // Other authentication method
}
} )
.catch( ... );
U2F is a challenge-response protocol. The server sends a challenge to the client, which responds with a response.
This library is intended to be used in the client (the browser). There is another package intended for server-side: https://www.npmjs.com/package/u2f
If you get BAD_REQUEST, the most common situations are that you either don't use https (which you must), or that the AppID doesn't match the server URI. In fact, the AppID must be exactly the base URI to your server (such as https://your-server.com), including the port if it isn't 443.
For more information, please see https://developers.yubico.com/U2F/Libraries/Client_error_codes.html and https://developers.yubico.com/U2F/App_ID.html
FAQs
Promisified U2F API for browsers
The npm package u2f-api receives a total of 38,115 weekly downloads. As such, u2f-api popularity was classified as popular.
We found that u2f-api demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."