feature/client-typescript

.gitignore

@@ -1,2 +1,3 @@
 **/node_modules/
-dist
+dist
+package-lock.json

packages/client/README.md

@@ -1,73 +1,29 @@
-# webauthn
+# @webauthn/client
 
-Implementation of strong authentication with the webauthn standard and FIDO2.
-Strong authentication is an authentication method using a physical key.
+This library contains convenience methods intended to simplify interactions with a browser's Webauthn API.
 
-For a more thorough introduction see these two nice articles:
-
-- [introduction](https://medium.com/@herrjemand/introduction-to-webauthn-api-5fd1fb46c285)
-- [verifying fido2 responses](https://medium.com/@herrjemand/verifying-fido2-responses-4691288c8770)
+This front end library complements this repo's [@webauthn/server](../server/) NodeJS library.
 
 ## Installation
 
 ```js
 npm install @webauthn/client
-npm install @webauthn/server
 ```
 
-## usage
-
-`Webauthn` is composed of two parts `@webauthn/client` and `@webauthn/server`
-
-### On the browser
+## Usage
 
 ```js
-import { 
+import {
     solveRegistrationChallenge,
     solveLoginChallenge
 } from '@webauthn/client';
 ```
 
-- `solveRegistrationChallenge`:
-    convert the challenge returned by the server on the register route into the response to be returned
-- `solveLoginChallenge`:
-    convert the challenge returned by the server on the login route into the response to be returned
-
-See an example in example/front
-
-### On the server
-
-```js
-import {
-    parseRegisterRequest,
-    generateRegistrationChallenge,
-    parseLoginRequest,
-    generateLoginChallenge,
-    verifyAuthenticatorAssertion,
-} from '@webauthn/server';
-```
-
-- `parseRegisterRequest`:
-    Extract challenge and key from the register request body. The challenge allow to retrieve the user, and the key must be stored server side linked to the user.
-- `generateRegistrationChallenge`:
-    Generate a challenge from a relying party and a user `{ relyingParty, user }` to be sent back to the client, in order to register
-- `parseLoginRequest`:
-    Extract challenge and KeyId from the login request.
-- `generateLoginChallenge`:
-    Generate challengeResponse from the key sent by the client during login. challengeResponse.challenge should be stored serverside linked to the corresponding user
-- `verifyAuthenticatorAssertion`:
-    Take the loginChallenge request body and the key stored with the user, and return true if it passes the authenticator assertion
-
-See an example in example/server
-
-
-## Roadmap
-
-For now only fido-u2f and packed format are implemented
-
-- Implement android-key format
-- Implement android-safetynet format
-- Implement tpm format
+- `solveRegistrationChallenge`: convert the challenge returned by the server on the register route into the response to be returned
+- `solveLoginChallenge`: convert the challenge returned by the server on the login route into the response to be returned
 
+See an example in [example/front](../../example/front/).
 
+## TypeScript support
 
+This client library's source files are 100% TypeScript. As a result every method is fully typed and supports use in both JavaScript and TypeScript projects.

packages/client/package.json

@@ -2,6 +2,7 @@
   "name": "@webauthn/client",
   "version": "0.1.3",
   "main": "dist/main.js",
+  "types": "dist/index.d.ts",
   "module": "src/index.js",
   "repository": {
     "type": "git",
@@ -14,15 +15,12 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "core-js": "^3.3.2",
-    "regenerator-runtime": "^0.13.3",
     "unibabel": "^2.1.7",
     "webpack": "^4.30.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.5.5",
-    "@babel/preset-env": "^7.5.5",
-    "babel-loader": "^8.0.6",
+    "ts-loader": "^6.2.1",
+    "typescript": "^3.7.4",
     "webpack-cli": "^3.3.1"
   }
 }

packages/client/src/index.ts

@@ -0,0 +1,8 @@
+export {
+    solveRegistrationChallenge,
+    RegistrationChallengeJSON,
+} from './solveRegistrationChallenge';
+export {
+    solveLoginChallenge,
+    LoginChallengeJSON,
+} from './solveLoginChallenge';

packages/client/src/solveLoginChallenge.ts

@@ -0,0 +1,49 @@
+import  { assertionToJSON, AssertionCredential, stringToBuffer, AssertionCredentialJSON } from './utils';
+
+/**
+ * JSON representation of an allowed Webauthn credential
+ */
+export interface AllowedCredentialJSON extends Omit<PublicKeyCredentialDescriptor, 'id'> {
+    id: string; // A base64-encoded Buffer
+}
+
+/**
+ * JSON-ified options to be passed into navigator.credentials.get(). These values are requested
+ * from the Relying Party (see `server > generateLoginChallenge()`), which responds with JSON
+ * containing ArrayBuffers converted to base64-encoded strings.
+ */
+export interface LoginChallengeJSON extends Omit<PublicKeyCredentialRequestOptions, 'challenge' | 'allowCredentials'> {
+    challenge: string; // A base64-encoded Buffer
+    allowCredentials?: AllowedCredentialJSON[];
+}
+
+/**
+ * Convert JSON-ified credential options into values for use in navigator.credentials.get()
+ */
+function loginChallengeToPublicKey (challenge: LoginChallengeJSON): PublicKeyCredentialRequestOptions {
+    let allowCredentials: PublicKeyCredentialDescriptor[];
+    if (Array.isArray(challenge.allowCredentials) && challenge.allowCredentials.length > 0) {
+        allowCredentials = challenge.allowCredentials.map(allowCredential => ({
+            ...allowCredential,
+            id: stringToBuffer(allowCredential.id),
+        }));
+    }
+
+    return {
+        ...challenge,
+        challenge: stringToBuffer(challenge.challenge),
+        // @ts-ignore 2454
+        allowCredentials,
+    };
+};
+
+/**
+ * Initiate the Webauthn Assertion process, then convert the results to JSON to POST back to the
+ * Relying Party (see `server > parseLoginRequest()`)
+ */
+export async function solveLoginChallenge (challenge: LoginChallengeJSON): Promise<AssertionCredentialJSON> {
+    const publicKey = loginChallengeToPublicKey(challenge);
+    const credential = (await navigator.credentials.get({ publicKey }) as AssertionCredential);
+
+    return assertionToJSON(credential);
+};

packages/client/src/solveRegistrationChallenge.ts

@@ -0,0 +1,40 @@
+import { attestationToJSON, AttestationCredential, stringToBuffer } from './utils';
+
+/**
+ * JSON-ified options to be passed into navigator.credentials.create(). These values are requested
+ * from the Relying Party (see `server > generateRegistrationChallenge()`), which responds with JSON
+ * containing ArrayBuffers converted to base64-encoded strings.
+ */
+export interface RegistrationChallengeJSON extends Omit<PublicKeyCredentialCreationOptions, 'challenge' | 'user'> {
+    challenge: string; // A base64-encoded Buffer
+    user: {
+        id: string; // A base64-encoded Buffer
+        displayName: string;
+        name: string;
+    },
+}
+
+/**
+ * Convert JSON-ified credential options into values for use in navigator.credentials.create()
+ */
+export function registrationChallengeToPublicKey (challenge: RegistrationChallengeJSON): PublicKeyCredentialCreationOptions {
+    return {
+        ...challenge,
+        challenge: stringToBuffer(challenge.challenge),
+        user: {
+            ...challenge.user,
+            id: stringToBuffer(challenge.user.id),
+        },
+    };
+}
+
+/**
+ * Initiate the Webauthn Attestation process, then convert the results to JSON to POST back to the
+ * Relying Party (see `server > parseRegisterRequest()`)
+ */
+export async function solveRegistrationChallenge (challenge: RegistrationChallengeJSON) {
+    const publicKey = registrationChallengeToPublicKey(challenge);
+    const credential = (await navigator.credentials.create({ publicKey }) as AttestationCredential);
+
+    return attestationToJSON(credential);
+}