From 2a26cc5afd8ec320ce80bb85ea31a190dfba6e13 Mon Sep 17 00:00:00 2001
From: Manav Rathi <manav@mrmr.io>
Date: Sun, 9 Jun 2024 11:21:55 +0530
Subject: [PATCH] Doc a bit

---
 .../accounts/src/pages/passkeys/verify.tsx    |  6 ++---
 web/apps/accounts/src/services/passkey.ts     | 27 +++++++++++++++----
 2 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/web/apps/accounts/src/pages/passkeys/verify.tsx b/web/apps/accounts/src/pages/passkeys/verify.tsx
index b3dec84c83..8a2c190abb 100644
--- a/web/apps/accounts/src/pages/passkeys/verify.tsx
+++ b/web/apps/accounts/src/pages/passkeys/verify.tsx
@@ -12,7 +12,7 @@ import { t } from "i18next";
 import _sodium from "libsodium-wrappers";
 import { useEffect, useState } from "react";
 import {
-    authenticatePasskey,
+    attestChallenge,
     beginPasskeyAuthentication,
     finishPasskeyAuthentication,
     isWebAuthnSupported,
@@ -99,9 +99,7 @@ const Page = () => {
 
         setStatus("waitingForUser");
 
-        const credential = await authenticatePasskey(
-            beginData.options.publicKey,
-        );
+        const credential = await attestChallenge(beginData.options.publicKey);
 
         if (!credential) {
             setStatus("failed");
diff --git a/web/apps/accounts/src/services/passkey.ts b/web/apps/accounts/src/services/passkey.ts
index 8f30c13a25..8ef4bbb96a 100644
--- a/web/apps/accounts/src/services/passkey.ts
+++ b/web/apps/accounts/src/services/passkey.ts
@@ -346,6 +346,18 @@ export interface BeginPasskeyAuthenticationResponse {
     };
 }
 
+/**
+ * Create a authentication ceremony session and return a challenge and a list of
+ * public key credentials that can be used to attest that challenge.
+ *
+ * [Note: WebAuthn authentication flow]
+ *
+ * This is step 1 of passkey authentication flow as described in
+ * https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API#authenticating_a_user
+ *
+ * @param passkeySessionID A session created by the requesting app that can be
+ * used to initiate a passkey authentication ceremony on the accounts app.
+ */
 export const beginPasskeyAuthentication = async (
     passkeySessionID: string,
 ): Promise<BeginPasskeyAuthenticationResponse> => {
@@ -374,14 +386,19 @@ export const beginPasskeyAuthentication = async (
 };
 
 /**
- * Authenticate the user with a passkey that the they had previously created for
- * the current domain.
+ * Authenticate the user by asking them to use a Passkey that the they had
+ * previously created for the current domain to attest a challenge.
  *
- * @param publicKey
+ * This function implements step 2 and 3 of the passkey authentication flow. See
+ * [Note: WebAuthn authentication flow].
  *
- * @returns A {@link PublicKeyCredential} whose response contains
+ * @param publicKey A challenge and a list of public key credentials
+ * ("passkeys") that can be used to attest that challenge.
+ *
+ * @returns A {@link PublicKeyCredential} whose response contains the attested
+ * challenge.
  */
-export const authenticatePasskey = async (
+export const attestChallenge = async (
     publicKey: PublicKeyCredentialRequestOptions,
 ) => {
     const timeoutMillis: number = 60000; // Default timeout of 60 seconds