@simplewebauthn/server 9.0.3 → 10.0.1

package/README.md

@@ -4,14 +4,14 @@
 [![npm (scoped)](https://img.shields.io/npm/v/@simplewebauthn/server?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@simplewebauthn/server)
 
 - [Installation](#installation)
-  - [Node LTS 16.x or higher](#node-lts-16x-or-higher)
+  - [Node LTS 20.x or higher](#node-lts-20x-or-higher)
   - [Deno v1.33.x or higher](#deno-v133x-or-higher)
 - [Usage](#usage)
 - [Supported Attestation Formats](#supported-attestation-formats)
 
 ## Installation
 
-### Node LTS 16.x or higher
+### Node LTS 20.x or higher
 
 This package is available on **npm** and supports **both CommonJS and
 [ECMAScript modules (ESM)](https://nodejs.org/api/esm.html#enabling)** projects:

package/esm/authentication/generateAuthenticationOptions.d.ts

@@ -1,23 +1,25 @@
-import type { AuthenticationExtensionsClientInputs, PublicKeyCredentialDescriptorFuture, PublicKeyCredentialRequestOptionsJSON, UserVerificationRequirement } from '../deps.js';
+import type { AuthenticationExtensionsClientInputs, AuthenticatorTransportFuture, Base64URLString, PublicKeyCredentialRequestOptionsJSON, UserVerificationRequirement } from '../deps.js';
 export type GenerateAuthenticationOptionsOpts = {
-    allowCredentials?: PublicKeyCredentialDescriptorFuture[];
+    rpID: string;
+    allowCredentials?: {
+        id: Base64URLString;
+        transports?: AuthenticatorTransportFuture[];
+    }[];
     challenge?: string | Uint8Array;
     timeout?: number;
     userVerification?: UserVerificationRequirement;
     extensions?: AuthenticationExtensionsClientInputs;
-    rpID?: string;
 };
 /**
- * Prepare a value to pass into navigator.credentials.get(...) for authenticator "login"
+ * Prepare a value to pass into navigator.credentials.get(...) for authenticator authentication
  *
- * @param allowCredentials Authenticators previously registered by the user, if any. If undefined
- * the client will ask the user which credential they want to use
- * @param challenge Random value the authenticator needs to sign and pass back
- * user for authentication
- * @param timeout How long (in ms) the user can take to complete authentication
- * @param userVerification Set to `'discouraged'` when asserting as part of a 2FA flow, otherwise
- * set to `'preferred'` or `'required'` as desired.
- * @param extensions Additional plugins the authenticator or browser should use during authentication
- * @param rpID Valid domain name (after `https://`)
+ * **Options:**
+ *
+ * @param rpID - Valid domain name (after `https://`)
+ * @param allowCredentials **(Optional)** - Authenticators previously registered by the user, if any. If undefined the client will ask the user which credential they want to use
+ * @param challenge **(Optional)** - Random value the authenticator needs to sign and pass back user for authentication. Defaults to generating a random value
+ * @param timeout **(Optional)** - How long (in ms) the user can take to complete authentication. Defaults to `60000`
+ * @param userVerification **(Optional)** - Set to `'discouraged'` when asserting as part of a 2FA flow, otherwise set to `'preferred'` or `'required'` as desired. Defaults to `"preferred"`
+ * @param extensions **(Optional)** - Additional plugins the authenticator or browser should use during authentication
  */
-export declare function generateAuthenticationOptions(options?: GenerateAuthenticationOptionsOpts): Promise<PublicKeyCredentialRequestOptionsJSON>;
+export declare function generateAuthenticationOptions(options: GenerateAuthenticationOptionsOpts): Promise<PublicKeyCredentialRequestOptionsJSON>;

package/esm/authentication/generateAuthenticationOptions.js

@@ -1,19 +1,18 @@
 import { isoBase64URL, isoUint8Array } from '../helpers/iso/index.js';
 import { generateChallenge } from '../helpers/generateChallenge.js';
 /**
- * Prepare a value to pass into navigator.credentials.get(...) for authenticator "login"
+ * Prepare a value to pass into navigator.credentials.get(...) for authenticator authentication
  *
- * @param allowCredentials Authenticators previously registered by the user, if any. If undefined
- * the client will ask the user which credential they want to use
- * @param challenge Random value the authenticator needs to sign and pass back
- * user for authentication
- * @param timeout How long (in ms) the user can take to complete authentication
- * @param userVerification Set to `'discouraged'` when asserting as part of a 2FA flow, otherwise
- * set to `'preferred'` or `'required'` as desired.
- * @param extensions Additional plugins the authenticator or browser should use during authentication
- * @param rpID Valid domain name (after `https://`)
+ * **Options:**
+ *
+ * @param rpID - Valid domain name (after `https://`)
+ * @param allowCredentials **(Optional)** - Authenticators previously registered by the user, if any. If undefined the client will ask the user which credential they want to use
+ * @param challenge **(Optional)** - Random value the authenticator needs to sign and pass back user for authentication. Defaults to generating a random value
+ * @param timeout **(Optional)** - How long (in ms) the user can take to complete authentication. Defaults to `60000`
+ * @param userVerification **(Optional)** - Set to `'discouraged'` when asserting as part of a 2FA flow, otherwise set to `'preferred'` or `'required'` as desired. Defaults to `"preferred"`
+ * @param extensions **(Optional)** - Additional plugins the authenticator or browser should use during authentication
  */
-export async function generateAuthenticationOptions(options = {}) {
+export async function generateAuthenticationOptions(options) {
     const { allowCredentials, challenge = await generateChallenge(), timeout = 60000, userVerification = 'preferred', extensions, rpID, } = options;
     /**
      * Preserve ability to specify `string` values for challenges
@@ -23,14 +22,20 @@ export async function generateAuthenticationOptions(options = {}) {
         _challenge = isoUint8Array.fromUTF8String(_challenge);
     }
     return {
+        rpId: rpID,
         challenge: isoBase64URL.fromBuffer(_challenge),
-        allowCredentials: allowCredentials?.map((cred) => ({
-            ...cred,
-            id: isoBase64URL.fromBuffer(cred.id),
-        })),
+        allowCredentials: allowCredentials?.map((cred) => {
+            if (!isoBase64URL.isBase64URL(cred.id)) {
+                throw new Error(`excludeCredential id "${cred.id}" is not a valid base64url string`);
+            }
+            return {
+                ...cred,
+                id: isoBase64URL.trimPadding(cred.id),
+                type: 'public-key',
+            };
+        }),
         timeout,
         userVerification,
         extensions,
-        rpId: rpID,
     };
 }

package/esm/authentication/verifyAuthenticationResponse.d.ts

@@ -1,36 +1,31 @@
-import type { AuthenticationResponseJSON, AuthenticatorDevice, CredentialDeviceType, UserVerificationRequirement } from '../deps.js';
+import type { AuthenticationResponseJSON, AuthenticatorDevice, Base64URLString, CredentialDeviceType, UserVerificationRequirement } from '../deps.js';
 import { AuthenticationExtensionsAuthenticatorOutputs } from '../helpers/decodeAuthenticatorExtensions.js';
 export type VerifyAuthenticationResponseOpts = {
     response: AuthenticationResponseJSON;
     expectedChallenge: string | ((challenge: string) => boolean | Promise<boolean>);
     expectedOrigin: string | string[];
     expectedRPID: string | string[];
-    expectedType?: string | string[];
     authenticator: AuthenticatorDevice;
+    expectedType?: string | string[];
     requireUserVerification?: boolean;
     advancedFIDOConfig?: {
         userVerification?: UserVerificationRequirement;
     };
 };
 /**
- * Verify that the user has legitimately completed the login process
+ * Verify that the user has legitimately completed the authentication process
  *
  * **Options:**
  *
- * @param response Response returned by **@simplewebauthn/browser**'s `startAssertion()`
- * @param expectedChallenge The base64url-encoded `options.challenge` returned by
- * `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 expectedType (Optional) The response type expected ('webauthn.get')
- * @param authenticator An internal {@link AuthenticatorDevice} matching the credential's ID
- * @param requireUserVerification (Optional) Enforce user verification by the authenticator
- * (via PIN, fingerprint, etc...)
- * @param advancedFIDOConfig (Optional) Options for satisfying more stringent FIDO RP feature
- * requirements
- * @param advancedFIDOConfig.userVerification (Optional) Enable alternative rules for evaluating the
- * User Presence and User Verified flags in authenticator data: UV (and UP) flags are optional
- * unless this value is `"required"`
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAssertion()`
+ * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `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
+ * @param expectedType **(Optional)** - The response type expected ('webauthn.get')
+ * @param requireUserVerification **(Optional)** - Enforce user verification by the authenticator (via PIN, fingerprint, etc...) Defaults to `true`
+ * @param advancedFIDOConfig **(Optional)** - Options for satisfying more stringent FIDO RP feature requirements
+ * @param advancedFIDOConfig.userVerification **(Optional)** - Enable alternative rules for evaluating the User Presence and User Verified flags in authenticator data: UV (and UP) flags are optional unless this value is `"required"`
  */
 export declare function verifyAuthenticationResponse(options: VerifyAuthenticationResponseOpts): Promise<VerifiedAuthenticationResponse>;
 /**
@@ -56,7 +51,7 @@ export declare function verifyAuthenticationResponse(options: VerifyAuthenticati
 export type VerifiedAuthenticationResponse = {
     verified: boolean;
     authenticationInfo: {
-        credentialID: Uint8Array;
+        credentialID: Base64URLString;
         newCounter: number;
         userVerified: boolean;
         credentialDeviceType: CredentialDeviceType;

package/esm/authentication/verifyAuthenticationResponse.js

@@ -6,24 +6,19 @@ import { parseBackupFlags } from '../helpers/parseBackupFlags.js';
 import { matchExpectedRPID } from '../helpers/matchExpectedRPID.js';
 import { isoBase64URL, isoUint8Array } from '../helpers/iso/index.js';
 /**
- * Verify that the user has legitimately completed the login process
+ * Verify that the user has legitimately completed the authentication process
  *
  * **Options:**
  *
- * @param response Response returned by **@simplewebauthn/browser**'s `startAssertion()`
- * @param expectedChallenge The base64url-encoded `options.challenge` returned by
- * `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 expectedType (Optional) The response type expected ('webauthn.get')
- * @param authenticator An internal {@link AuthenticatorDevice} matching the credential's ID
- * @param requireUserVerification (Optional) Enforce user verification by the authenticator
- * (via PIN, fingerprint, etc...)
- * @param advancedFIDOConfig (Optional) Options for satisfying more stringent FIDO RP feature
- * requirements
- * @param advancedFIDOConfig.userVerification (Optional) Enable alternative rules for evaluating the
- * User Presence and User Verified flags in authenticator data: UV (and UP) flags are optional
- * unless this value is `"required"`
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAssertion()`
+ * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `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
+ * @param expectedType **(Optional)** - The response type expected ('webauthn.get')
+ * @param requireUserVerification **(Optional)** - Enforce user verification by the authenticator (via PIN, fingerprint, etc...) Defaults to `true`
+ * @param advancedFIDOConfig **(Optional)** - Options for satisfying more stringent FIDO RP feature requirements
+ * @param advancedFIDOConfig.userVerification **(Optional)** - Enable alternative rules for evaluating the User Presence and User Verified flags in authenticator data: UV (and UP) flags are optional unless this value is `"required"`
  */
 export async function verifyAuthenticationResponse(options) {
     const { response, expectedChallenge, expectedOrigin, expectedRPID, expectedType, authenticator, requireUserVerification = true, advancedFIDOConfig, } = options;
@@ -84,10 +79,10 @@ export async function verifyAuthenticationResponse(options) {
             throw new Error(`Unexpected authentication response origin "${origin}", expected "${expectedOrigin}"`);
         }
     }
-    if (!isoBase64URL.isBase64url(assertionResponse.authenticatorData)) {
+    if (!isoBase64URL.isBase64URL(assertionResponse.authenticatorData)) {
         throw new Error('Credential response authenticatorData was not a base64url string');
     }
-    if (!isoBase64URL.isBase64url(assertionResponse.signature)) {
+    if (!isoBase64URL.isBase64URL(assertionResponse.signature)) {
         throw new Error('Credential response signature was not a base64url string');
     }
     if (assertionResponse.userHandle &&

package/esm/deps.d.ts

@@ -1,4 +1,4 @@
-export type { AttestationConveyancePreference, AuthenticationExtensionsClientInputs, AuthenticationResponseJSON, AuthenticatorDevice, AuthenticatorSelectionCriteria, Base64URLString, COSEAlgorithmIdentifier, CredentialDeviceType, Crypto, PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialDescriptorFuture, PublicKeyCredentialParameters, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON, UserVerificationRequirement, } from '@simplewebauthn/types';
+export type { AttestationConveyancePreference, AuthenticationExtensionsClientInputs, AuthenticationResponseJSON, AuthenticatorDevice, AuthenticatorSelectionCriteria, AuthenticatorTransportFuture, Base64URLString, COSEAlgorithmIdentifier, CredentialDeviceType, Crypto, PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialParameters, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON, UserVerificationRequirement, } from '@simplewebauthn/types';
 export * as tinyCbor from '@levischuck/tiny-cbor';
 export { default as base64 } from '@hexagon/base64';
 export { fetch as crossFetch } from 'cross-fetch';

package/esm/helpers/convertCertBufferToPEM.js

@@ -8,7 +8,7 @@ export function convertCertBufferToPEM(certBuffer) {
      * Get certBuffer to a base64 representation
      */
     if (typeof certBuffer === 'string') {
-        if (isoBase64URL.isBase64url(certBuffer)) {
+        if (isoBase64URL.isBase64URL(certBuffer)) {
             b64cert = isoBase64URL.toBase64(certBuffer);
         }
         else if (isoBase64URL.isBase64(certBuffer)) {

package/esm/helpers/decodeClientDataJSON.d.ts

@@ -1,7 +1,8 @@
+import type { Base64URLString } from '../deps.js';
 /**
  * Decode an authenticator's base64url-encoded clientDataJSON to JSON
  */
-export declare function decodeClientDataJSON(data: string): ClientDataJSON;
+export declare function decodeClientDataJSON(data: Base64URLString): ClientDataJSON;
 export type ClientDataJSON = {
     type: string;
     challenge: string;

package/esm/helpers/decodeClientDataJSON.js

@@ -3,7 +3,7 @@ import { isoBase64URL } from './iso/index.js';
  * Decode an authenticator's base64url-encoded clientDataJSON to JSON
  */
 export function decodeClientDataJSON(data) {
-    const toString = isoBase64URL.toString(data);
+    const toString = isoBase64URL.toUTF8String(data);
     const clientData = JSON.parse(toString);
     return _decodeClientDataJSONInternals.stubThis(clientData);
 }

package/esm/helpers/generateUserID.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generate a suitably random value to be used as user ID
+ */
+export declare function generateUserID(): Promise<Uint8Array>;
+export declare const _generateUserIDInternals: {
+    stubThis: (value: Uint8Array) => Uint8Array;
+};

package/esm/helpers/generateUserID.js

@@ -0,0 +1,17 @@
+import { isoCrypto } from './iso/index.js';
+/**
+ * Generate a suitably random value to be used as user ID
+ */
+export async function generateUserID() {
+    /**
+     * WebAuthn spec says user.id has a max length of 64 bytes. I prefer how 32 random bytes look
+     * after they're base64url-encoded so I'm choosing to go with that here.
+     */
+    const newUserID = new Uint8Array(32);
+    await isoCrypto.getRandomValues(newUserID);
+    return _generateUserIDInternals.stubThis(newUserID);
+}
+// Make it possible to stub the return value during testing
+export const _generateUserIDInternals = {
+    stubThis: (value) => value,
+};

package/esm/helpers/index.d.ts

@@ -5,6 +5,7 @@ import { decodeAttestationObject } from './decodeAttestationObject.js';
 import { decodeClientDataJSON } from './decodeClientDataJSON.js';
 import { decodeCredentialPublicKey } from './decodeCredentialPublicKey.js';
 import { generateChallenge } from './generateChallenge.js';
+import { generateUserID } from './generateUserID.js';
 import { getCertificateInfo } from './getCertificateInfo.js';
 import { isCertRevoked } from './isCertRevoked.js';
 import { parseAuthenticatorData } from './parseAuthenticatorData.js';
@@ -13,7 +14,7 @@ import { validateCertificatePath } from './validateCertificatePath.js';
 import { verifySignature } from './verifySignature.js';
 import { isoBase64URL, isoCBOR, isoCrypto, isoUint8Array } from './iso/index.js';
 import * as cose from './cose.js';
-export { convertAAGUIDToString, convertCertBufferToPEM, convertCOSEtoPKCS, cose, decodeAttestationObject, decodeClientDataJSON, decodeCredentialPublicKey, generateChallenge, getCertificateInfo, isCertRevoked, isoBase64URL, isoCBOR, isoCrypto, isoUint8Array, parseAuthenticatorData, toHash, validateCertificatePath, verifySignature, };
+export { convertAAGUIDToString, convertCertBufferToPEM, convertCOSEtoPKCS, cose, decodeAttestationObject, decodeClientDataJSON, decodeCredentialPublicKey, generateChallenge, generateUserID, getCertificateInfo, isCertRevoked, isoBase64URL, isoCBOR, isoCrypto, isoUint8Array, parseAuthenticatorData, toHash, validateCertificatePath, verifySignature, };
 import type { AttestationFormat, AttestationObject, AttestationStatement } from './decodeAttestationObject.js';
 import type { CertificateInfo } from './getCertificateInfo.js';
 import type { ClientDataJSON } from './decodeClientDataJSON.js';

package/esm/helpers/index.js

@@ -5,6 +5,7 @@ import { decodeAttestationObject } from './decodeAttestationObject.js';
 import { decodeClientDataJSON } from './decodeClientDataJSON.js';
 import { decodeCredentialPublicKey } from './decodeCredentialPublicKey.js';
 import { generateChallenge } from './generateChallenge.js';
+import { generateUserID } from './generateUserID.js';
 import { getCertificateInfo } from './getCertificateInfo.js';
 import { isCertRevoked } from './isCertRevoked.js';
 import { parseAuthenticatorData } from './parseAuthenticatorData.js';
@@ -13,4 +14,4 @@ import { validateCertificatePath } from './validateCertificatePath.js';
 import { verifySignature } from './verifySignature.js';
 import { isoBase64URL, isoCBOR, isoCrypto, isoUint8Array } from './iso/index.js';
 import * as cose from './cose.js';
-export { convertAAGUIDToString, convertCertBufferToPEM, convertCOSEtoPKCS, cose, decodeAttestationObject, decodeClientDataJSON, decodeCredentialPublicKey, generateChallenge, getCertificateInfo, isCertRevoked, isoBase64URL, isoCBOR, isoCrypto, isoUint8Array, parseAuthenticatorData, toHash, validateCertificatePath, verifySignature, };
+export { convertAAGUIDToString, convertCertBufferToPEM, convertCOSEtoPKCS, cose, decodeAttestationObject, decodeClientDataJSON, decodeCredentialPublicKey, generateChallenge, generateUserID, getCertificateInfo, isCertRevoked, isoBase64URL, isoCBOR, isoCrypto, isoUint8Array, parseAuthenticatorData, toHash, validateCertificatePath, verifySignature, };

package/esm/helpers/iso/isoBase64URL.d.ts

@@ -1,3 +1,4 @@
+import type { Base64URLString } from '../../deps.js';
 /**
  * Decode from a Base64URL-encoded string to an ArrayBuffer. Best used when converting a
  * credential ID from a JSON string to an ArrayBuffer, like in allowCredentials or
@@ -20,13 +21,13 @@ export declare function fromBuffer(buffer: Uint8Array, to?: 'base64' | 'base64ur
  */
 export declare function toBase64(base64urlString: string): string;
 /**
- * Encode a string to base64url
+ * Encode a UTF-8 string to base64url
  */
-export declare function fromString(ascii: string): string;
+export declare function fromUTF8String(utf8String: string): string;
 /**
- * Decode a base64url string into its original string
+ * Decode a base64url string into its original UTF-8 string
  */
-export declare function toString(base64urlString: string): string;
+export declare function toUTF8String(base64urlString: string): string;
 /**
  * Confirm that the string is encoded into base64
  */
@@ -34,4 +35,8 @@ export declare function isBase64(input: string): boolean;
 /**
  * Confirm that the string is encoded into base64url, with support for optional padding
  */
-export declare function isBase64url(input: string): boolean;
+export declare function isBase64URL(input: string): boolean;
+/**
+ * Remove optional padding from a base64url-encoded string
+ */
+export declare function trimPadding(input: Base64URLString): Base64URLString;

package/esm/helpers/iso/isoBase64URL.js

@@ -30,15 +30,15 @@ export function toBase64(base64urlString) {
     return toBase64;
 }
 /**
- * Encode a string to base64url
+ * Encode a UTF-8 string to base64url
  */
-export function fromString(ascii) {
-    return base64.fromString(ascii, true);
+export function fromUTF8String(utf8String) {
+    return base64.fromString(utf8String, true);
 }
 /**
- * Decode a base64url string into its original string
+ * Decode a base64url string into its original UTF-8 string
  */
-export function toString(base64urlString) {
+export function toUTF8String(base64urlString) {
     return base64.toString(base64urlString, true);
 }
 /**
@@ -50,8 +50,14 @@ export function isBase64(input) {
 /**
  * Confirm that the string is encoded into base64url, with support for optional padding
  */
-export function isBase64url(input) {
+export function isBase64URL(input) {
     // Trim padding characters from the string if present
-    input = input.replace(/=/g, '');
+    input = trimPadding(input);
     return base64.validate(input, true);
 }
+/**
+ * Remove optional padding from a base64url-encoded string
+ */
+export function trimPadding(input) {
+    return input.replace(/=/g, '');
+}