From 38db065749c70f553612e027070ccc9914bfbc71 Mon Sep 17 00:00:00 2001 From: Andreas Coroiu Date: Wed, 27 Sep 2023 11:03:04 +0200 Subject: [PATCH] [PM-2014] chore: document requests and responses --- .../request/save-credential.request.ts | 15 +++++++++++++-- ...webauthn-login-attestation-response.request.ts | 8 ++++++-- ...authn-login-authenticator-response.request.ts} | 6 +++++- ...hn-login-credential-create-options.response.ts | 9 +++++++++ .../webauthn-login-credential.response.ts | 3 +++ 5 files changed, 36 insertions(+), 5 deletions(-) rename apps/web/src/app/auth/core/services/webauthn-login/request/{webauthn-login-response.request.ts => webauthn-login-authenticator-response.request.ts} (59%) diff --git a/apps/web/src/app/auth/core/services/webauthn-login/request/save-credential.request.ts b/apps/web/src/app/auth/core/services/webauthn-login/request/save-credential.request.ts index 2ab5feb22fe..ffd0e6cf709 100644 --- a/apps/web/src/app/auth/core/services/webauthn-login/request/save-credential.request.ts +++ b/apps/web/src/app/auth/core/services/webauthn-login/request/save-credential.request.ts @@ -1,7 +1,18 @@ -import { WebauthnLoginResponseRequest } from "./webauthn-login-response.request"; +import { WebauthnLoginAttestationResponseRequest } from "./webauthn-login-attestation-response.request"; +/** + * Request sent to the server to save a newly created webauthn login credential. + */ export class SaveCredentialRequest { - deviceResponse: WebauthnLoginResponseRequest; + /** The response recieved from the authenticator. This contains the public key */ + deviceResponse: WebauthnLoginAttestationResponseRequest; + + /** Nickname chosen by the user to identify this credential */ name: string; + + /** + * Token required by the server to complete the creation. + * It contains encrypted information that the server needs to verify the credential. + */ token: string; } diff --git a/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-attestation-response.request.ts b/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-attestation-response.request.ts index 91922f420ae..4b33896290c 100644 --- a/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-attestation-response.request.ts +++ b/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-attestation-response.request.ts @@ -1,8 +1,12 @@ import { Utils } from "@bitwarden/common/platform/misc/utils"; -import { WebauthnLoginResponseRequest } from "./webauthn-login-response.request"; +import { WebauthnLoginAuthenticatorResponseRequest } from "./webauthn-login-authenticator-response.request"; -export class WebauthnLoginAttestationResponseRequest extends WebauthnLoginResponseRequest { +/** + * The response recieved from an authentiator after a successful attestation. + * This request is used to save newly created webauthn login credentials to the server. + */ +export class WebauthnLoginAttestationResponseRequest extends WebauthnLoginAuthenticatorResponseRequest { response: { attestationObject: string; clientDataJson: string; diff --git a/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-response.request.ts b/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-authenticator-response.request.ts similarity index 59% rename from apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-response.request.ts rename to apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-authenticator-response.request.ts index fd36d07c678..9e332ad5381 100644 --- a/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-response.request.ts +++ b/apps/web/src/app/auth/core/services/webauthn-login/request/webauthn-login-authenticator-response.request.ts @@ -1,6 +1,10 @@ import { Utils } from "@bitwarden/common/platform/misc/utils"; -export abstract class WebauthnLoginResponseRequest { +/** + * An abstract class that represents responses recieved from the webauthn authenticator. + * It contains data that is commonly returned during different types of authenticator interactions. + */ +export abstract class WebauthnLoginAuthenticatorResponseRequest { id: string; rawId: string; type: string; diff --git a/apps/web/src/app/auth/core/services/webauthn-login/response/webauthn-login-credential-create-options.response.ts b/apps/web/src/app/auth/core/services/webauthn-login/response/webauthn-login-credential-create-options.response.ts index 9c14ac139be..ce588207727 100644 --- a/apps/web/src/app/auth/core/services/webauthn-login/response/webauthn-login-credential-create-options.response.ts +++ b/apps/web/src/app/auth/core/services/webauthn-login/response/webauthn-login-credential-create-options.response.ts @@ -1,8 +1,17 @@ import { ChallengeResponse } from "@bitwarden/common/auth/models/response/two-factor-web-authn.response"; import { BaseResponse } from "@bitwarden/common/models/response/base.response"; +/** + * Options provided by the server to be used during attestation (i.e. creation of a new webauthn credential) + */ export class WebauthnLoginCredentialCreateOptionsResponse extends BaseResponse { + /** Options to be provided to the webauthn authenticator */ options: ChallengeResponse; + + /** + * Contains an encrypted version of the {@link options}. + * Used by the server to validate the attestation response of newly created credentials. + */ token: string; constructor(response: unknown) { diff --git a/apps/web/src/app/auth/core/services/webauthn-login/response/webauthn-login-credential.response.ts b/apps/web/src/app/auth/core/services/webauthn-login/response/webauthn-login-credential.response.ts index c6746051b3f..7a7f5199e7c 100644 --- a/apps/web/src/app/auth/core/services/webauthn-login/response/webauthn-login-credential.response.ts +++ b/apps/web/src/app/auth/core/services/webauthn-login/response/webauthn-login-credential.response.ts @@ -1,5 +1,8 @@ import { BaseResponse } from "@bitwarden/common/models/response/base.response"; +/** + * A webauthn login credential recieved from the server. + */ export class WebauthnLoginCredentialResponse extends BaseResponse { id: string; name: string;