🐞 Admin Portal: Stale key-download tab exposes a technical backend error

packages/admin-portal/src/components/keys-ceremony/DownloadStep.tsx

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 import {useMutation} from "@apollo/client"
 import React, {useContext, useState} from "react"
-import {FormControlLabel, FormGroup, Typography, Checkbox} from "@mui/material"
+import {Alert, FormControlLabel, FormGroup, Typography, Checkbox} from "@mui/material"
 import ArrowForwardIosIcon from "@mui/icons-material/ArrowForwardIos"
 import DownloadIcon from "@mui/icons-material/Download"
 import ArrowBackIosIcon from "@mui/icons-material/ArrowBackIos"
@@ -18,8 +18,14 @@ import {AuthContext} from "@/providers/AuthContextProvider"
 import {WizardStyles} from "@/components/styles/WizardStyles"
 import {GET_PRIVATE_KEY} from "@/queries/GetPrivateKey"
 import {Dialog} from "@sequentech/ui-essentials"
-import {useNotify} from "react-admin"
+import {useGetOne, useNotify} from "react-admin"
 import {useAliasRenderer} from "@/hooks/useAliasRenderer"
+import {SettingsContext} from "@/providers/SettingsContextProvider"
+import {
+    IKeysCeremonyExecutionStatus as EStatus,
+    IKeysCeremonyTrusteeStatus as TStatus,
+} from "@/services/KeyCeremony"
+import {isPrivateKeyDownloadUnavailableError} from "@/services/privateKeyDownloadError"
 
 export interface DownloadStepProps {
     electionEvent: Sequent_Backend_Election_Event
@@ -36,10 +42,12 @@ export const DownloadStep: React.FC<DownloadStepProps> = ({
 }) => {
     const {t} = useTranslation()
     const authContext = useContext(AuthContext)
+    const {globalSettings} = useContext(SettingsContext)
     const [downloaded, setDownloaded] = useState<boolean>(false)
     const [downloading, setDownloading] = useState<boolean>(false)
     const [openConfirmationModal, setOpenConfirmationModal] = useState(false)
     const [errors, setErrors] = useState<String | null>(null)
+    const [downloadUnavailable, setDownloadUnavailable] = useState(false)
     const notify = useNotify()
     const aliasRenderer = useAliasRenderer()
 
@@ -57,10 +65,30 @@ export const DownloadStep: React.FC<DownloadStepProps> = ({
     }
     const {firstCheckbox, secondCheckbox} = checkboxState
 
+    const {data: latestCeremony} = useGetOne<Sequent_Backend_Keys_Ceremony>(
+        "sequent_backend_keys_ceremony",
+        {id: currentCeremony.id},
+        {refetchInterval: globalSettings.QUERY_FAST_POLL_INTERVAL_MS}
+    )
+    const isDownloadUnavailable =
+        downloadUnavailable ||
+        (latestCeremony?.execution_status ?? currentCeremony.execution_status) !==
+            EStatus.IN_PROGRESS
+    const trusteeStatus = (latestCeremony?.status ?? currentCeremony.status)?.trustees?.find(
+        (trustee: {name: string}) => trustee.name === authContext.trustee
+    )?.status
+    const downloadUnavailableMessage =
+        trusteeStatus === TStatus.KEY_CHECKED
+            ? "keysGeneration.downloadStep.alreadyVerified"
+            : "keysGeneration.downloadStep.unavailable"
+
     const [getPrivateKeysMutation] = useMutation<GetPrivateKeyMutation>(GET_PRIVATE_KEY)
     const download = async () => {
         setErrors(null)
         setDownloaded(false)
+        if (isDownloadUnavailable) {
+            return
+        }
         setDownloading(true)
         try {
             const {data, errors} = await getPrivateKeysMutation({
@@ -71,9 +99,11 @@ export const DownloadStep: React.FC<DownloadStepProps> = ({
             })
             setDownloading(false)
             if (errors) {
-                setErrors(
-                    t("keysGeneration.downloadStep.errorDownloading", {error: errors.toString()})
-                )
+                if (isPrivateKeyDownloadUnavailableError({graphQLErrors: errors})) {
+                    setDownloadUnavailable(true)
+                } else {
+                    setErrors(t("keysGeneration.downloadStep.unexpectedError"))
+                }
                 return null
             } else {
                 const privateKey = data?.get_private_key?.private_key_base64
@@ -92,11 +122,13 @@ export const DownloadStep: React.FC<DownloadStepProps> = ({
                 tempLink.click()
                 setDownloaded(true)
             }
-        } catch (exception: any) {
+        } catch (exception: unknown) {
             setDownloading(false)
-            setErrors(
-                t("keysGeneration.downloadStep.errorDownloading", {error: exception.toString()})
-            )
+            if (isPrivateKeyDownloadUnavailableError(exception)) {
+                setDownloadUnavailable(true)
+            } else {
+                setErrors(t("keysGeneration.downloadStep.unexpectedError"))
+            }
             return null
         }
     }
@@ -116,19 +148,23 @@ export const DownloadStep: React.FC<DownloadStepProps> = ({
                     <WizardStyles.DownloadButton
                         color="primary"
                         onClick={download}
+                        disabled={downloading || isDownloadUnavailable}
                         className="keys-download-download-button"
                     >
                         <DownloadIcon />
                         {t("keysGeneration.downloadStep.downloadButton")}
                     </WizardStyles.DownloadButton>
                     <WizardStyles.StatusBox>
                         {downloading ? <WizardStyles.DownloadProgress /> : null}
+                        {isDownloadUnavailable ? (
+                            <Alert severity="info">{t(downloadUnavailableMessage)}</Alert>
+                        ) : null}
                         {downloaded ? (
                             <WizardStyles.SucessMessage
                                 variant="body1"
                                 className="keys-download-success"
                             >
-                                {t("keysGeneration.checkStep.downloaded")}
+                                {t("keysGeneration.downloadStep.downloaded")}
                             </WizardStyles.SucessMessage>
                         ) : null}
                         {errors ? (

packages/admin-portal/src/services/privateKeyDownloadError.test.ts

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Sequent Tech Inc <legal@sequentech.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+    isPrivateKeyDownloadUnavailableError,
+    PRIVATE_KEY_DOWNLOAD_UNAVAILABLE_ERROR_CODE,
+} from "./privateKeyDownloadError"
+
+describe("isPrivateKeyDownloadUnavailableError", () => {
+    it("recognizes a direct Hasura error code", () => {
+        expect(
+            isPrivateKeyDownloadUnavailableError({
+                graphQLErrors: [{extensions: {code: PRIVATE_KEY_DOWNLOAD_UNAVAILABLE_ERROR_CODE}}],
+            })
+        ).toBe(true)
+    })
+
+    it("recognizes a code in the action response body", () => {
+        expect(
+            isPrivateKeyDownloadUnavailableError({
+                graphQLErrors: [
+                    {
+                        extensions: {
+                            internal: {
+                                response: {
+                                    body: JSON.stringify({
+                                        extensions: {
+                                            code: PRIVATE_KEY_DOWNLOAD_UNAVAILABLE_ERROR_CODE,
+                                        },
+                                    }),
+                                },
+                            },
+                        },
+                    },
+                ],
+            })
+        ).toBe(true)
+    })
+
+    it("rejects unrelated and malformed errors", () => {
+        expect(
+            isPrivateKeyDownloadUnavailableError({
+                graphQLErrors: [
+                    {extensions: {code: "InternalServerError"}},
+                    {extensions: {internal: {response: {body: "not json"}}}},
+                ],
+            })
+        ).toBe(false)
+        expect(isPrivateKeyDownloadUnavailableError(new Error("Network error"))).toBe(false)
+    })
+})

packages/admin-portal/src/services/privateKeyDownloadError.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Sequent Tech Inc <legal@sequentech.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {IGraphQLActionError} from "@sequentech/ui-core"
+import {parseActionResponseBody} from "./graphqlActionError"
+
+export const PRIVATE_KEY_DOWNLOAD_UNAVAILABLE_ERROR_CODE = "PrivateKeyDownloadUnavailable"
+
+export const isPrivateKeyDownloadUnavailableError = (error: unknown): boolean => {
+    const actionError = error as IGraphQLActionError | undefined
+
+    return (
+        actionError?.graphQLErrors?.some((graphQLError) => {
+            if (graphQLError.extensions?.code === PRIVATE_KEY_DOWNLOAD_UNAVAILABLE_ERROR_CODE) {
+                return true
+            }
+
+            const responseBody = parseActionResponseBody(
+                graphQLError.extensions?.internal?.response?.body
+            ) as {extensions?: {code?: unknown}} | undefined
+
+            return responseBody?.extensions?.code === PRIVATE_KEY_DOWNLOAD_UNAVAILABLE_ERROR_CODE
+        }) === true
+    )
+}

packages/admin-portal/src/translations/cat.ts

@@ -2026,8 +2026,12 @@ const catalanTranslation: TranslationType = {
                 subtitle:
                     "Per continuar, si us plau descarrega i guarda la teva Clau Privada Encriptada en almenys dos dispositius diferents:",
                 downloadButton: "Descarregar la teva Clau Privada Encriptada",
-                errorDownloading: "Error de descàrrega: {{error}}",
+                downloaded: "Clau Privada Encriptada descarregada correctament.",
                 errorEmptyKey: "Error de descàrrega, fitxer buit",
+                unexpectedError: "No s'ha pogut descarregar la clau privada. Torna-ho a provar.",
+                alreadyVerified: "La teva clau privada ja s'havia descarregat i verificat.",
+                unavailable:
+                    "La descàrrega de la clau privada ja no està disponible perquè la cerimònia ha avançat.",
                 confirmdDialog: {
                     ok: "Confirmar còpies de seguretat i Continuar",
                     cancel: "Tornar",
@@ -2048,7 +2052,6 @@ const catalanTranslation: TranslationType = {
                     "Còpia de Seguretat de la Clau Encriptada Privada invàlida, si us plau intenta-ho de nou",
                 errorEmptyFile: "Fitxer buit o no trobat",
                 verified: "Còpia de seguretat verificada correctament.",
-                downloaded: "Clau Encriptada Privada generada amb èxit.",
             },
         },
         miruExport: {

packages/admin-portal/src/translations/en.ts

@@ -1993,8 +1993,12 @@ const englishTranslation = {
                 subtitle:
                     "To continue, please download and store your Encrypted Private Key at least into two different devices:",
                 downloadButton: "Download your Encrypted Private Key",
-                errorDownloading: "Download error: {{error}}",
+                downloaded: "Encrypted Private Key downloaded successfully.",
                 errorEmptyKey: "Download error, empty file",
+                unexpectedError: "The private key could not be downloaded. Please try again.",
+                alreadyVerified: "Your private key was already downloaded and verified.",
+                unavailable:
+                    "Private key download is no longer available because the ceremony has moved on.",
                 confirmdDialog: {
                     ok: "Confirm Backups and Continue",
                     cancel: "Go Back",
@@ -2014,7 +2018,6 @@ const englishTranslation = {
                 errorUploading: "Invalid Encrypted Private Key Backup, please try again",
                 errorEmptyFile: "File empty or not found",
                 verified: "Backup verified successfully.",
-                downloaded: "Encrypted Private Key generated successfully.",
             },
         },
         miruExport: {

packages/admin-portal/src/translations/es.ts

@@ -2016,8 +2016,12 @@ const spanishTranslation: TranslationType = {
                 subtitle:
                     "Para continuar, por favor descarga y guarda tu Clave Privada Encriptada en al menos dos dispositivos diferentes:",
                 downloadButton: "Descargar tu Clave Privada Encriptada",
-                errorDownloading: "Error de descarga: {{error}}",
+                downloaded: "Clave Privada Encriptada descargada correctamente.",
                 errorEmptyKey: "Error de descarga, fichero vacío",
+                unexpectedError: "No se pudo descargar la clave privada. Inténtalo de nuevo.",
+                alreadyVerified: "Tu clave privada ya se había descargado y verificado.",
+                unavailable:
+                    "La descarga de la clave privada ya no está disponible porque la ceremonia ha avanzado.",
                 confirmdDialog: {
                     ok: "Confirmar copias de seguridad y Continuar",
                     cancel: "Volver",
@@ -2038,7 +2042,6 @@ const spanishTranslation: TranslationType = {
                     "Copa de Seguridad de la Clave Encriptada Privada inválida, por favor inténtalo de nuevo",
                 errorEmptyFile: "Fichero vacío o no encontrado",
                 verified: "Copia de seguridad verificada correctamente.",
-                downloaded: "Clave Encriptada Privada generada exitosamente.",
             },
         },
         miruExport: {

packages/admin-portal/src/translations/eu.ts

@@ -2009,8 +2009,12 @@ const basqueTranslation: TranslationType = {
                 subtitle:
                     "Jarraitzeko, mesedez deskargatu eta gorde zure Zifratutako Giltza Pribatua gutxienez bi gailu desberdinetan:",
                 downloadButton: "Deskargatu zure Zifratutako Giltza Pribatua",
-                errorDownloading: "Deskarga errorea: {{error}}",
+                downloaded: "Zifratutako Giltza Pribatua behar bezala deskargatu da.",
                 errorEmptyKey: "Deskarga errorea, fitxategi hutsa",
+                unexpectedError: "Ezin izan da gako pribatua deskargatu. Saiatu berriro.",
+                alreadyVerified: "Zure gako pribatua deskargatuta eta egiaztatuta zegoen.",
+                unavailable:
+                    "Gako pribatuaren deskarga jada ez dago erabilgarri, zeremoniak aurrera egin duelako.",
                 confirmdDialog: {
                     ok: "Berretsi Babeskopiak eta Jarraitu",
                     cancel: "Itzuli",
@@ -2031,7 +2035,6 @@ const basqueTranslation: TranslationType = {
                     "Zifratutako Giltza Pribatu Babeskopia baliogabea, mesedez saiatu berriro",
                 errorEmptyFile: "Fitxategia hutsa edo ez da aurkitu",
                 verified: "Babeskopia arrakastaz egiaztatua.",
-                downloaded: "Zifratutako Giltza Pribatua arrakastaz sortua.",
             },
         },
         miruExport: {

packages/admin-portal/src/translations/fr.ts

@@ -2029,8 +2029,12 @@ const frenchTranslation: TranslationType = {
                 subtitle:
                     "Pour continuer, veuillez télécharger et sauvegarder votre Clé Privée Cryptée sur au moins deux appareils différents :",
                 downloadButton: "Télécharger votre Clé Privée Cryptée",
-                errorDownloading: "Erreur de téléchargement : {{error}}",
+                downloaded: "Clé Privée Cryptée téléchargée avec succès.",
                 errorEmptyKey: "Erreur de téléchargement, fichier vide",
+                unexpectedError: "La clé privée n'a pas pu être téléchargée. Veuillez réessayer.",
+                alreadyVerified: "Votre clé privée a déjà été téléchargée et vérifiée.",
+                unavailable:
+                    "Le téléchargement de la clé privée n'est plus disponible car la cérémonie a progressé.",
                 confirmdDialog: {
                     ok: "Confirmer les copies de sauvegarde et Continuer",
                     cancel: "Revenir",
@@ -2051,7 +2055,6 @@ const frenchTranslation: TranslationType = {
                     "Copa de Sauvegarde de la Clé Privée Cryptée invalide, veuillez réessayer",
                 errorEmptyFile: "Fichier vide ou non trouvé",
                 verified: "Copie de sauvegarde vérifiée avec succès.",
-                downloaded: "Clé Privée Cryptée générée avec succès.",
             },
         },
         miruExport: {

packages/admin-portal/src/translations/gl.ts

@@ -2015,8 +2015,12 @@ const galegoTranslation: TranslationType = {
                 subtitle:
                     "Para continuar, por favor descarga e almacena a túa Chave Privada Cifrada en polo menos dous dispositivos diferentes:",
                 downloadButton: "Descargar a túa Chave Privada Cifrada",
-                errorDownloading: "Erro de descarga: {{error}}",
+                downloaded: "Chave Privada Cifrada descargada correctamente.",
                 errorEmptyKey: "Erro de descarga, ficheiro baleiro",
+                unexpectedError: "Non se puido descargar a clave privada. Téntao de novo.",
+                alreadyVerified: "A túa chave privada xa se descargara e verificara.",
+                unavailable:
+                    "A descarga da clave privada xa non está dispoñible porque a cerimonia avanzou.",
                 confirmdDialog: {
                     ok: "Confirmar Copias de Seguridade e Continuar",
                     cancel: "Volver Atrás",
@@ -2037,7 +2041,6 @@ const galegoTranslation: TranslationType = {
                     "Copia de Seguridade da Chave Privada Cifrada inválida, por favor intenta de novo",
                 errorEmptyFile: "Ficheiro baleiro ou non atopado",
                 verified: "Copia de seguridade verificada correctamente.",
-                downloaded: "Chave Privada Cifrada xerada correctamente.",
             },
         },
         miruExport: {

packages/admin-portal/src/translations/nl.ts

@@ -2014,8 +2014,12 @@ const dutchTranslation: TranslationType = {
                 subtitle:
                     "Om door te gaan, download en bewaar uw Versleutelde Privésleutel op minstens twee verschillende apparaten:",
                 downloadButton: "Download uw Versleutelde Privésleutel",
-                errorDownloading: "Downloadfout: {{error}}",
+                downloaded: "Versleutelde privésleutel succesvol gedownload.",
                 errorEmptyKey: "Downloadfout, leeg bestand",
+                unexpectedError: "De privésleutel kon niet worden gedownload. Probeer het opnieuw.",
+                alreadyVerified: "Uw privésleutel was al gedownload en geverifieerd.",
+                unavailable:
+                    "De privésleutel kan niet meer worden gedownload omdat de ceremonie is gevorderd.",
                 confirmdDialog: {
                     ok: "Back-ups Bevestigen en Doorgaan",
                     cancel: "Terug",
@@ -2035,7 +2039,6 @@ const dutchTranslation: TranslationType = {
                 errorUploading: "Ongeldige Back-up van Versleutelde Privésleutel, probeer opnieuw",
                 errorEmptyFile: "Bestand leeg of niet gevonden",
                 verified: "Back-up succesvol geverifieerd.",
-                downloaded: "Versleutelde Privésleutel succesvol gegenereerd.",
             },
         },
         miruExport: {

packages/admin-portal/src/translations/tl.ts

@@ -2020,8 +2020,12 @@ const tagalogTranslation: TranslationType = {
                 subtitle:
                     "Upang magpatuloy, mangyaring i-download at itago ang iyong Encrypted Private Key sa hindi bababa sa dalawang magkaibang device:",
                 downloadButton: "I-download ang iyong Encrypted Private Key",
-                errorDownloading: "Error sa pag-download: {{error}}",
+                downloaded: "Matagumpay na na-download ang Encrypted Private Key.",
                 errorEmptyKey: "Error sa pag-download, walang laman na file",
+                unexpectedError: "Hindi ma-download ang pribadong key. Pakisubukang muli.",
+                alreadyVerified: "Na-download at na-verify na ang iyong pribadong key.",
+                unavailable:
+                    "Hindi na maaaring i-download ang pribadong key dahil nagpatuloy na ang seremonya.",
                 confirmdDialog: {
                     ok: "Kumpirmahin ang mga Backup at Magpatuloy",
                     cancel: "Bumalik",
@@ -2041,7 +2045,6 @@ const tagalogTranslation: TranslationType = {
                 errorUploading: "Di-wastong Encrypted Private Key Backup, mangyaring subukan muli",
                 errorEmptyFile: "Walang laman na file o hindi natagpuan",
                 verified: "Backup ay matagumpay na nasuri.",
-                downloaded: "Encrypted Private Key ay matagumpay na nabuo.",
             },
         },
         miruExport: {