fix/554-server-docstrings-tlc

packages/server/src/authentication/generateAuthenticationOptions.ts

@@ -21,17 +21,16 @@ export type GenerateAuthenticationOptionsOpts = {
 };
 
 /**
- * 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: GenerateAuthenticationOptionsOpts,

packages/server/src/authentication/verifyAuthenticationResponse.ts

@@ -19,33 +19,28 @@ export type VerifyAuthenticationResponseOpts = {
  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 async function verifyAuthenticationResponse(
  options: VerifyAuthenticationResponseOpts,

packages/server/src/registration/generateRegistrationOptions.ts

@@ -79,25 +79,22 @@ const defaultAuthenticatorSelection: AuthenticatorSelectionCriteria = {
 const defaultSupportedAlgorithmIDs: COSEAlgorithmIdentifier[] = [-8, -7, -257];
 
 /**
- * Prepare a value to pass into navigator.credentials.create(...) for authenticator "registration"
+ * Prepare a value to pass into navigator.credentials.create(...) for authenticator registration
  *
  * **Options:**
  *
- * @param rpName User-visible, "friendly" website/service name
- * @param rpID Valid domain name (after `https://`)
- * @param userID User's website-specific unique ID
- * @param userName User's website-specific username (email, etc...)
- * @param challenge Random value the authenticator needs to sign and pass back
- * @param userDisplayName User's actual name
- * @param timeout How long (in ms) the user can take to complete attestation
- * @param attestationType Specific attestation statement
- * @param excludeCredentials Authenticators registered by the user so the user can't register the
- * same credential multiple times
- * @param authenticatorSelection Advanced criteria for restricting the types of authenticators that
- * may be used
- * @param extensions Additional plugins the authenticator or browser should use during attestation
- * @param supportedAlgorithmIDs Array of numeric COSE algorithm identifiers supported for
- * attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms
+ * @param rpName - User-visible, "friendly" website/service name
+ * @param rpID - Valid domain name (after `https://`)
+ * @param userName - User's website-specific username (email, etc...)
+ * @param userID **(Optional)** - User's website-specific unique ID. Defaults to generating a random identifier
+ * @param challenge **(Optional)** - Random value the authenticator needs to sign and pass back. Defaults to generating a random value
+ * @param userDisplayName **(Optional)** - User's actual name. Defaults to `""`
+ * @param timeout **(Optional)** - How long (in ms) the user can take to complete attestation. Defaults to `60000`
+ * @param attestationType **(Optional)** - Specific attestation statement. Defaults to `"none"`
+ * @param excludeCredentials **(Optional)** - Authenticators registered by the user so the user can't register the same credential multiple times. Defaults to `[]`
+ * @param authenticatorSelection **(Optional)** - Advanced criteria for restricting the types of authenticators that may be used. Defaults to `{ residentKey: 'preferred', userVerification: 'preferred' }`
+ * @param extensions **(Optional)** - Additional plugins the authenticator or browser should use during attestation
+ * @param supportedAlgorithmIDs **(Optional)** - Array of numeric COSE algorithm identifiers supported for attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms. Defaults to `[-8, -7, -257]`
  */
 export async function generateRegistrationOptions(
  options: GenerateRegistrationOptionsOpts,

packages/server/src/registration/verifyRegistrationResponse.ts

@@ -44,16 +44,13 @@ export type VerifyRegistrationResponseOpts = {
  *
  * **Options:**
  *
- * @param response Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
- * @param expectedChallenge The base64url-encoded `options.challenge` returned by
- * `generateRegistrationOptions()`
- * @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.create')
- * @param requireUserVerification (Optional) Enforce user verification by the authenticator
- * (via PIN, fingerprint, etc...)
- * @param supportedAlgorithmIDs Array of numeric COSE algorithm identifiers supported for
- * attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms
+ * @param response - Response returned by **@simplewebauthn/browser**'s `startAuthentication()`
+ * @param expectedChallenge - The base64url-encoded `options.challenge` returned by `generateRegistrationOptions()`
+ * @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.create')
+ * @param requireUserVerification **(Optional)** - Enforce user verification by the authenticator (via PIN, fingerprint, etc...) Defaults to `true`
+ * @param supportedAlgorithmIDs **(Optional)** - Array of numeric COSE algorithm identifiers supported for attestation by this RP. See https://www.iana.org/assignments/cose/cose.xhtml#algorithms. Defaults to all supported algorithm IDs
  */
 export async function verifyRegistrationResponse(
  options: VerifyRegistrationResponseOpts,