From 1f3d99c25c70a9b216ce75360c85f0c3daedbc0a Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Fri, 28 Jul 2023 15:29:34 +0100
Subject: [PATCH] Improve comments on key-setup dialogs (#11339)

* Remove outdated (I think) TODO

* Improve comments on key-setup dialogs
---
 .../dialogs/security/CreateKeyBackupDialog.tsx | 18 +++++++++++++++---
 .../security/CreateSecretStorageDialog.tsx     | 15 ++++++---------
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/src/async-components/views/dialogs/security/CreateKeyBackupDialog.tsx b/src/async-components/views/dialogs/security/CreateKeyBackupDialog.tsx
index c188319b3a..2a02945621 100644
--- a/src/async-components/views/dialogs/security/CreateKeyBackupDialog.tsx
+++ b/src/async-components/views/dialogs/security/CreateKeyBackupDialog.tsx
@@ -45,9 +45,13 @@ interface IState {
     error?: boolean;
 }
 
-/*
- * Walks the user through the process of creating an e2e key backup
- * on the server.
+/**
+ * Walks the user through the process of setting up e2e key backups to a new backup, and storing the decryption key in
+ * SSSS.
+ *
+ * Uses {@link accessSecretStorage}, which means that if 4S is not already configured, it will be bootstrapped (which
+ * involves displaying an {@link CreateSecretStorageDialog} so the user can enter a passphrase and/or download the 4S
+ * key).
  */
 export default class CreateKeyBackupDialog extends React.PureComponent<IProps, IState> {
     public constructor(props: IProps) {
@@ -75,6 +79,14 @@ export default class CreateKeyBackupDialog extends React.PureComponent<IProps, I
         const cli = MatrixClientPeg.safeGet();
         try {
             await accessSecretStorage(async (): Promise<void> => {
+                // `accessSecretStorage` will have bootstrapped secret storage if necessary, so we can now
+                // set up key backup.
+                //
+                // XXX: `bootstrapSecretStorage` also sets up key backup as a side effect, so there is a 90% chance
+                // this is actually redundant.
+                //
+                // The only time it would *not* be redundant would be if, for some reason, we had working 4S but no
+                // working key backup. (For example, if the user clicked "Delete Backup".)
                 info = await cli.prepareKeyBackupVersion(null /* random key */, {
                     secureSecretStorage: true,
                 });
diff --git a/src/async-components/views/dialogs/security/CreateSecretStorageDialog.tsx b/src/async-components/views/dialogs/security/CreateSecretStorageDialog.tsx
index 62b4502cef..ba53b615a3 100644
--- a/src/async-components/views/dialogs/security/CreateSecretStorageDialog.tsx
+++ b/src/async-components/views/dialogs/security/CreateSecretStorageDialog.tsx
@@ -94,9 +94,12 @@ interface IState {
     error?: boolean;
 }
 
-/*
- * Walks the user through the process of creating a passphrase to guard Secure
- * Secret Storage in account data.
+/**
+ * Walks the user through the process of creating a 4S passphrase and bootstrapping secret storage.
+ *
+ * If the user already has a key backup, follows a "migration" flow (aka "Upgrade your encryption") which
+ * prompts the user to enter their backup decryption password (a Curve25519 private key, possibly derived
+ * from a passphrase), and uses that as the (AES) 4S encryption key.
  */
 export default class CreateSecretStorageDialog extends React.PureComponent<IProps, IState> {
     public static defaultProps: Partial<IProps> = {
@@ -576,12 +579,6 @@ export default class CreateSecretStorageDialog extends React.PureComponent<IProp
     }
 
     private renderPhaseMigrate(): JSX.Element {
-        // TODO: This is a temporary screen so people who have the labs flag turned on and
-        // click the button are aware they're making a change to their account.
-        // Once we're confident enough in this (and it's supported enough) we can do
-        // it automatically.
-        // https://github.com/vector-im/element-web/issues/11696
-
         let authPrompt;
         let nextCaption = _t("Next");
         if (this.state.canUploadKeysWithPasswordOnly) {