# web-eid.js · [![npm version](https://badge.fury.io/js/web-eid.svg)](https://www.npmjs.com/package/web-eid) [![Bower version](https://badge.fury.io/bo/web-eid.svg)](https://github.com/web-eid/web-eid.js)

 [`web-eid.js`](./web-eid.js) is a ultrathin wrapper on top of the [messaging interface](https://github.com/web-eid/web-eid/wiki/MessagingAPI) provided by the [Web eID app](https://github.com/web-eid/web-eid), either via [`web-eid-extension`](https://github.com/web-eid/web-eid-extension) [HTML5 postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) interface or [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) or some other message transport in the future (like Android Intents)

It makes using the features provided by Web eID installation as available via [web-eid.com](https://web-eid.com) super-easy:

- provides an asynchronous, Promise-based DWIM interface
- listens to incoming messages and turns them into resolved Promises

## Installation

### Browser installation
Just download the file and use it in a script tag

    <script src="web-eid.js"></script>

Functionality shall be bound to `window.webeid`

## Bower
    $ bower install --save web-eid

## Webpack & Browserify
    $ npm install --save web-eid

And simply

    webeid = require('web-eid');

### Note for IE users
IE 11 does not have [`Promise` support](http://caniuse.com/#search=promise), thus a polyfill is required.

# API
- All calls are asynchronous in nature and return a Promise
- While asynchronous, the API is still sequential - only one call can be serviced by a smart card (reader) at a time. If a call can not be serviced because this reason, the promise shall be rejected
- The `message` property of a rejected promise (an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)) shall contain a symbolic error code that can be parsed
- Conformance to https://www.w3.org/2001/tag/doc/promises-guide is intended

## Note about API and stability
At this point of time no API stability is assured. Please note that if `window.hwcrypto` from [hwcrypto.js](https://github.com/hwcrypto/hwcrypto.js) is detected, `hwcrypto.getCertificate()` and `hwcrypto.sign()` are monkeypatched.

#### Timeouts
By default the execution time of a call depends on the underlying hardware and timeout is infinite. A timeout can be set for some calls, so that the operations that depend on user action would fail sooner (e.g. do not wait forever but fail in 2 minutes, if the user does not connect a card reader and insert a card in time) or set to `0` to get an instant error code. Please note that not all calls are cancelable on all platforms, due to unerlying platform limitations.

### `isAvailable`
```javascript
webeid.isAvailable(object options)
```

| parameter  | type        |                                 |
|------------|-------------|---------------------------------|
| `options`  | object      | additional options (_optional_) |

| `options` |                                                 |
|-----------|-------------------------------------------------|
| `timeout` | timeout in seconds or `Infinity`. Default is `0`|


- resolves to `false` if client software is not available or to a string that describes the connection type of the application (`webextension` or `websocket`)
- if `false`, the recommended action is to display a notice with a link to https://web-eid.com
- if called with `timeout = Infinity`, the recommended action is to display a dynamic notice during the call that asks the user to install or start the client app
- recommended use: guard function before dynamicallly showing login button; general client availability check before calling rest of the API etc

## PKI operations
If a PKI call fails, the promise shall be rejected with an `Error` object, which `message` property shall be a string from [CKR_* series](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.html#_Toc385057886) (PKCS#11, CNG/CryptoAPI return codes are mapped)

### `authenticate`
```javascript
webeid.authenticate(string nonce, object options)
```

| parameter  | type        |                                      |
|------------|-------------|--------------------------------------|
| `nonce`    | string      | nonce for the session (**required**) |
| `options`  | object      | additional options (_optional_)      |


| `options` |                                                        |
|-----------|--------------------------------------------------------|
| `timeout` | timeout in seconds or `Infinity`. Default is `Infinity`|

- resolves to a `string` containing the JWT token. JWT token description: https://github.com/martinpaljak/x509-webauth/wiki/OpenID-X509-ID-Token
- possible reasons for rejection: timeout or user cancels authentication, no certificates available, some other technical error
- used certificate is available in the `x5c` header field of the JWT token.
- expected behavior: user is instructed though the process of attaching a reader and a card, if necessary
- possible changes: resolving to `undefined` when no certificates are available

### `getCertificate`
```javascript
webeid.getCertificate(object options)
```

| parameter  | type        |                                 |
|------------|-------------|---------------------------------|
| `options`  | object      | additional options (_optional_) |

| `options` |                                                        |
|-----------|--------------------------------------------------------|
| `filter`  | type of certificate to return. Default is `sign`       |
| `timeout` | timeout in seconds or `Infinity`. Default is `Infinity`|

- resolves to an `ArrayBuffer` with the certificate
- intended to be used with the following `webeid.sign()` operation
- expected behavior: user is instructed though the process of attaching a reader and a card, if necessary
- possible reasons for rejection: user cancels certificate selection, no certificates available, some other technical error
- possible changes: resolving to `undefined` when no certificates available

### `sign`
```javascript
webeid.sign(ArrayBuffer certificate, ArrayBuffer hash, object options)
```

| parameter     | type        |                                   |
|---------------|-------------|-----------------------------------|
| `certificate` | ArrayBuffer | certificate to use (**required**) |
| `hash`        | ArrayBuffer | hash to sign (**required**)       |
| `options`     | object      | additional options (_optional_)   |


| `options`  |                                                        |
|------------|--------------------------------------------------------|
| `hashalgo` | hash algorithm type (`"SHA-256"` etc). (**required**)  |
| `timeout`  | timeout in seconds or `Infinity`. Default is `Infinity`|


- resolves to a `ArrayBuffer` containing the signature of the `hash` parameter (ArrayBuffer) generated with the private key belonging to the `certificate` (ArrayBuffer). Hash type is specified in `options.hashalgo` (`string`) and is one of "SHA-256", "SHA-384", "SHA-512"
- possible reasons for rejection: user cancels/refuses signing, user PIN is blocked, some other technical error
- possible changes: support for "last round on card" hashing

## WebSocket operations
### `authenticatedWebSocket`
```javascript
webeid.authenticatedWebSocket(string url, object options)
```

| parameter     | type        |                                   |
|---------------|-------------|-----------------------------------|
| `url`         | string      | URL to connect to (**required**)  |
| `options`     | object      | additional options (_optional_)   |

| `options`           |                                                            |
|---------------------|------------------------------------------------------------|
| `autoclose`         | set to `true` to close the socket when the card is removed |
| `timeout`           | timeout in seconds or `Infinity`. Default is `Infinity`    |

- the first message from the service MUST be JSON and MUST contain the nonce `{"nonce": "noncevalue"}`
- `authenticate()` is called with the nonce
- the authentication token is sent back to the service as JSON `{"token": "authenticationtoken"}`
- promise is resolved with the WebSocket object
- if a card remove event is detected and autoclose is enabled, the socket is closed

## PC/SC operations
- if rejected, the message of the Error object for PC/SC operations shall be a [PC/SC API error code](https://pcsclite.alioth.debian.org/api/group__ErrorCodes.html) as a string (e.g. `"SCARD_E_NOT_TRANSACTED"`)

### `connect`
```
webeid.connect(object options)
```

| parameter  | type        |                                 |
|------------|-------------|---------------------------------|
| `options`  | object      | additional options (_optional_) |

| `options` |                                                        |
|-----------|--------------------------------------------------------|
| `atrs`    | list of expected ATR-s in base64. Default is `[]`      |
| `protocol`| protocol to use (`T=0`, `T=1`, `*`. Default is `*`      |
| `timeout` | timeout in seconds or `Infinity`. Default is `Infinity`|

- resolves to a `Reader` object
  - `name` - `string` - name of the reader
  - `protocol` - `string` - protocol of the connection (`T=0` or `T=1`)
  - `atr` - `ArrayBuffer` - ATR of the card, as reported by the host PC/SC API
  - `transmit(ArrayBuffer)` - `function` - transmits the APDU to the card, returns a Promise that resolves to the response
  - `disconnect()` - `function`- disconnects the card, returns a Promise
  - `reconnect(string protocol)` - `function` - reconnects with the specified protocol, returns a Promise
- equivalent for [`SCardConnect`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379474(v=vs.85).aspx) in the PC/SC API
- `SCardConnect` is called with `SCARD_SHARE_EXCLUSIVE` or if it is not possible, with `SCARD_SHARE_SHARED` and a `SCardBeginTransaction()` on non-Windows machines

### `Reader.transmit(bytes)`
- resolves to `ArrayBuffer` of the response
- equivalent of [`SCardTransmit`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379804(v=vs.85).aspx) in PC/SC API
- resembles [transmitRaw](https://globalplatform.github.io/WebApis-for-SE/doc/#dom-channel-transmitraw), without the tidbits of channels or `61XX`/`6CXX` handling
- comparable for [transceive()](https://developer.android.com/reference/android/nfc/tech/IsoDep.html#transceive(byte[])) in Android IsoDep API

### `Reader.control(code, bytes)`
- resolves to `ArrayBuffer` of the response
- equivalent for [`SCardControl`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379474(v=vs.85).aspx) in PC/SC API

### `Reader.reconnect(protocol)`
- resolves to `true`. `Reader` object properties `protocol` and `atr` might have changed
- equivalent for [`SCardReconnect`](hhttps://msdn.microsoft.com/en-us/library/windows/desktop/aa379797(v=vs.85).aspx) in PC/SC API

### `Reader.disconnect()`
- equivalent for [`SCardDisconnect`](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379475(v=vs.85).aspx) in PC/SC API
- `SCardDisconnect` is called with `SCARD_RESET_CARD` argument

## Error codes
- `SCARD_E_READER_UNAVAILABLE` - if `webeid.connect()` has not been called or the reader has disappeared
- `SCARD_E_SHARING_VIOLATION` - if `webeid.connect()` can not establish a reliable (no interference from other applications on the computer) connection to the card