feat/webauthn-L3-json-types

packages/browser/src/helpers/toAuthenticatorAttachment.ts

@@ -0,0 +1,18 @@
+import { AuthenticatorAttachment } from '@simplewebauthn/typescript-types';
+
+const attachments: AuthenticatorAttachment[] = ['cross-platform', 'platform'];
+
+/**
+ * If possible coerce a `string` value into a known `AuthenticatorAttachment`
+ */
+export function toAuthenticatorAttachment(attachment: string | null): AuthenticatorAttachment | undefined {
+  if (!attachment) {
+    return;
+  }
+
+  if (attachments.indexOf(attachment as AuthenticatorAttachment) < 0) {
+    return;
+  }
+
+  return attachment as AuthenticatorAttachment;
+}

packages/browser/src/methods/startAuthentication.test.ts

@@ -115,7 +115,7 @@ test('should return base64url-encoded response values', async () => {
           userHandle: Buffer.from(mockUserHandle, 'ascii'),
         },
         getClientExtensionResults: () => ({}),
-        type: 'webauthn.get',
+        type: 'public-key',
         authenticatorAttachment: '',
       });
     });
@@ -299,7 +299,7 @@ test('should return authenticatorAttachment if present', async () => {
     return new Promise(resolve => {
       resolve({
         response: {},
-        getClientExtensionResults: () => {},
+        getClientExtensionResults: () => { },
         authenticatorAttachment: 'cross-platform',
       });
     });

packages/browser/src/methods/startAuthentication.ts

@@ -1,7 +1,7 @@
 import {
   PublicKeyCredentialRequestOptionsJSON,
   AuthenticationCredential,
-  AuthenticationCredentialJSON,
+  AuthenticationResponseJSON,
 } from '@simplewebauthn/typescript-types';
 
 import { bufferToBase64URLString } from '../helpers/bufferToBase64URLString';
@@ -12,18 +12,19 @@ import { browserSupportsWebAuthnAutofill } from '../helpers/browserSupportsWebAu
 import { toPublicKeyCredentialDescriptor } from '../helpers/toPublicKeyCredentialDescriptor';
 import { identifyAuthenticationError } from '../helpers/identifyAuthenticationError';
 import { webauthnAbortService } from '../helpers/webAuthnAbortService';
+import { toAuthenticatorAttachment } from '../helpers/toAuthenticatorAttachment';
 
 /**
  * Begin authenticator "login" via WebAuthn assertion
  *
- * @param requestOptionsJSON Output from **@simplewebauthn/server**'s generateAssertionOptions(...)
+ * @param requestOptionsJSON Output from **@simplewebauthn/server**'s `generateAuthenticationOptions(...)`
  * @param useBrowserAutofill Initialize conditional UI to enable logging in via browser
  * autofill prompts
  */
 export async function startAuthentication(
   requestOptionsJSON: PublicKeyCredentialRequestOptionsJSON,
   useBrowserAutofill = false,
-): Promise<AuthenticationCredentialJSON> {
+): Promise<AuthenticationResponseJSON> {
   if (!browserSupportsWebAuthn()) {
     throw new Error('WebAuthn is not supported in this browser');
   }
@@ -105,6 +106,6 @@ export async function startAuthentication(
     },
     type,
     clientExtensionResults: credential.getClientExtensionResults(),
-    authenticatorAttachment: credential.authenticatorAttachment,
+    authenticatorAttachment: toAuthenticatorAttachment(credential.authenticatorAttachment),
   };
 }

packages/browser/src/methods/startRegistration.test.ts

@@ -102,7 +102,7 @@ test('should return base64url-encoded response values', async () => {
           getPublicKeyAlgorithm: () => -999,
         },
         getClientExtensionResults: () => ({}),
-        type: 'webauthn.create',
+        type: 'public-key',
         authenticatorAttachment: '',
       });
     });
@@ -219,9 +219,9 @@ test('should return "cable" transport from response', async () => {
     type: 'webauthn.create',
   });
 
-  const response = await startRegistration(goodOpts1);
+  const regResponse = await startRegistration(goodOpts1);
 
-  expect(response.transports).toEqual(['cable']);
+  expect(regResponse.response.transports).toEqual(['cable']);
 });
 
 test('should cancel an existing call when executed again', async () => {
@@ -239,7 +239,7 @@ test('should return authenticatorAttachment if present', async () => {
     return new Promise(resolve => {
       resolve({
         response: {},
-        getClientExtensionResults: () => {},
+        getClientExtensionResults: () => { },
         authenticatorAttachment: 'cross-platform',
       });
     });

packages/browser/src/methods/startRegistration.ts

@@ -1,7 +1,8 @@
 import {
   PublicKeyCredentialCreationOptionsJSON,
   RegistrationCredential,
-  RegistrationCredentialJSON,
+  RegistrationResponseJSON,
+  AuthenticatorTransportFuture,
 } from '@simplewebauthn/typescript-types';
 
 import { utf8StringToBuffer } from '../helpers/utf8StringToBuffer';
@@ -11,6 +12,7 @@ import { browserSupportsWebAuthn } from '../helpers/browserSupportsWebAuthn';
 import { toPublicKeyCredentialDescriptor } from '../helpers/toPublicKeyCredentialDescriptor';
 import { identifyRegistrationError } from '../helpers/identifyRegistrationError';
 import { webauthnAbortService } from '../helpers/webAuthnAbortService';
+import { toAuthenticatorAttachment } from '../helpers/toAuthenticatorAttachment';
 
 /**
  * Begin authenticator "registration" via WebAuthn attestation
@@ -19,7 +21,7 @@ import { webauthnAbortService } from '../helpers/webAuthnAbortService';
  */
 export async function startRegistration(
   creationOptionsJSON: PublicKeyCredentialCreationOptionsJSON,
-): Promise<RegistrationCredentialJSON> {
+): Promise<RegistrationResponseJSON> {
   if (!browserSupportsWebAuthn()) {
     throw new Error('WebAuthn is not supported in this browser');
   }
@@ -32,7 +34,7 @@ export async function startRegistration(
       ...creationOptionsJSON.user,
       id: utf8StringToBuffer(creationOptionsJSON.user.id),
     },
-    excludeCredentials: creationOptionsJSON.excludeCredentials.map(toPublicKeyCredentialDescriptor),
+    excludeCredentials: creationOptionsJSON.excludeCredentials?.map(toPublicKeyCredentialDescriptor),
   };
 
   // Finalize options
@@ -54,25 +56,22 @@ export async function startRegistration(
 
   const { id, rawId, response, type } = credential;
 
-  // Convert values to base64 to make it easier to send back to the server
-  const credentialJSON: RegistrationCredentialJSON = {
+  // Continue to play it safe with `getTransports()` for now, even when L3 types say it's required
+  let transports: AuthenticatorTransportFuture[] | undefined = undefined;
+  if (typeof response.getTransports === 'function') {
+    transports = response.getTransports();
+  }
+
+  return {
     id,
     rawId: bufferToBase64URLString(rawId),
     response: {
       attestationObject: bufferToBase64URLString(response.attestationObject),
       clientDataJSON: bufferToBase64URLString(response.clientDataJSON),
+      transports,
     },
     type,
     clientExtensionResults: credential.getClientExtensionResults(),
-    authenticatorAttachment: credential.authenticatorAttachment,
+    authenticatorAttachment: toAuthenticatorAttachment(credential.authenticatorAttachment),
   };
-
-  /**
-   * Include the authenticator's transports if the browser supports querying for them
-   */
-  if (typeof response.getTransports === 'function') {
-    credentialJSON.transports = response.getTransports();
-  }
-
-  return credentialJSON;
 }

packages/server/src/authentication/verifyAuthenticationResponse.test.ts

@@ -5,7 +5,7 @@ import * as esmParseAuthenticatorData from '../helpers/parseAuthenticatorData';
 import { toHash } from '../helpers/toHash';
 import {
   AuthenticatorDevice,
-  AuthenticationCredentialJSON,
+  AuthenticationResponseJSON,
 } from '@simplewebauthn/typescript-types';
 import { isoUint8Array, isoBase64URL } from '../helpers/iso';
 
@@ -202,7 +202,6 @@ test.skip('should verify TPM assertion', async () => {
       },
       type: 'public-key',
       clientExtensionResults: {},
-      authenticatorAttachment: '',
     },
     expectedChallenge,
     expectedOrigin: assertionOrigin,
@@ -283,7 +282,6 @@ test('should pass verification if custom challenge verifier returns true', async
       },
       type: 'public-key',
       clientExtensionResults: {},
-      authenticatorAttachment: '',
     },
     expectedChallenge: (challenge: string) => {
       const parsedChallenge: { actualChallenge: string; arbitraryData: string } = JSON.parse(
@@ -335,7 +333,6 @@ test('should return authenticator extension output', async () => {
       rawId: 'E_Pko4wN1BXE23S0ftN3eQ',
       type: 'public-key',
       clientExtensionResults: {},
-      authenticatorAttachment: '',
     },
     expectedOrigin: 'android:apk-key-hash:gx7sq_pxhxhrIQdLyfG0pxKwiJ7hOk2DJQ4xvKd438Q',
     expectedRPID: 'try-webauthn.appspot.com',
@@ -384,7 +381,7 @@ test('should return credential backup info', async () => {
  * Assertion examples below
  */
 
-const assertionResponse: AuthenticationCredentialJSON = {
+const assertionResponse: AuthenticationResponseJSON = {
   id: 'KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew',
   rawId: 'KEbWNCc7NgaYnUyrNeFGX9_3Y-8oJ3KwzjnaiD1d1LVTxR7v3CaKfCz2Vy_g_MHSh7yJ8yL0Pxg6jo_o0hYiew',
   response: {
@@ -399,7 +396,6 @@ const assertionResponse: AuthenticationCredentialJSON = {
   },
   clientExtensionResults: {},
   type: 'public-key',
-  authenticatorAttachment: '',
 };
 const assertionChallenge = isoBase64URL.fromString('totallyUniqueValueEveryTime');
 const assertionOrigin = 'https://dev.dontneeda.pw';
@@ -417,7 +413,7 @@ const authenticator: AuthenticatorDevice = {
 /**
  * Represented a device that's being used on the website for the first time
  */
-const assertionFirstTimeUsedResponse: AuthenticationCredentialJSON = {
+const assertionFirstTimeUsedResponse: AuthenticationResponseJSON = {
   id: 'wSisR0_4hlzw3Y1tj4uNwwifIhRa-ZxWJwWbnfror0pVK9qPdBPO5pW3gasPqn6wXHb0LNhXB_IrA1nFoSQJ9A',
   rawId: 'wSisR0_4hlzw3Y1tj4uNwwifIhRa-ZxWJwWbnfror0pVK9qPdBPO5pW3gasPqn6wXHb0LNhXB_IrA1nFoSQJ9A',
   response: {
@@ -429,7 +425,6 @@ const assertionFirstTimeUsedResponse: AuthenticationCredentialJSON = {
   },
   type: 'public-key',
   clientExtensionResults: {},
-  authenticatorAttachment: '',
 };
 const assertionFirstTimeUsedChallenge = isoBase64URL.fromString('totallyUniqueValueEveryAssertion');
 const assertionFirstTimeUsedOrigin = 'https://dev.dontneeda.pw';

packages/server/src/authentication/verifyAuthenticationResponse.ts

@@ -1,5 +1,5 @@
 import {
-  AuthenticationCredentialJSON,
+  AuthenticationResponseJSON,
   AuthenticatorDevice,
   CredentialDeviceType,
   UserVerificationRequirement,
@@ -15,7 +15,7 @@ import { matchExpectedRPID } from '../helpers/matchExpectedRPID';
 import { isoUint8Array, isoBase64URL } from '../helpers/iso';
 
 export type VerifyAuthenticationResponseOpts = {
-  credential: AuthenticationCredentialJSON;
+  credential: AuthenticationResponseJSON;
   expectedChallenge: string | ((challenge: string) => boolean);
   expectedOrigin: string | string[];
   expectedRPID: string | string[];
@@ -33,7 +33,7 @@ export type VerifyAuthenticationResponseOpts = {
  *
  * @param credential Authenticator credential returned by browser's `startAssertion()`
  * @param expectedChallenge The base64url-encoded `options.challenge` returned by
- * `generateAssertionOptions()`
+ * `generateAuthenticationOptions()`
  * @param expectedOrigin Website URL (or array of URLs) that the registration should have occurred on
  * @param expectedRPID RP ID (or array of IDs) that was specified in the registration options
  * @param authenticator An internal {@link AuthenticatorDevice} matching the credential's ID