feat(web): explain missing challenge capabilities

Author: fionera

web/index.html

@@ -22,6 +22,7 @@ <h3 class="heading">Request on Hold</h3>
       </p>
     </noscript>
     <p id="cookie-warning" style="display: none">You need to enable Cookies to verify your Browser.</p>
+    <div id="capability-errors" class="capability-errors" style="display: none"></div>
     <p>If you suspect that you are being blocked by mistake, make sure that you have the
       latest browser version installed and all active browser plugins are disabled.</p>
     <p>If you see this and the verification repeats, please try a different browser.</p>

web/src/challange/capabilities.js

@@ -0,0 +1,45 @@
+const advice = {
+    textEncoder: {
+        name: "Text encoding",
+        message: "This challenge needs the browser TextEncoder API.",
+        fix: "Use an up-to-date browser with JavaScript enabled.",
+    },
+    webCrypto: {
+        name: "Web Crypto",
+        message: "This challenge needs the Web Crypto API.",
+        fix: "Use an up-to-date browser over HTTPS and disable extensions that block crypto.subtle.",
+    },
+    worker: {
+        name: "Web Workers",
+        message: "This challenge must run in a Web Worker.",
+        fix: "Disable extensions that block Web Workers or try a standard browser configuration.",
+    },
+};
+
+/**
+ * Return advice only for missing capabilities required by this challenge.
+ *
+ * @param {number} challengeType
+ * @param {{environment?: object, nativeCrypto?: boolean}} [options]
+ * @return {{name: string, message: string, fix: string}[]}
+ */
+export function detectMissingCapabilities(challengeType, {
+    environment = globalThis,
+    nativeCrypto = import.meta.env.VITE_NATIVE_CRYPTO === "true",
+} = {}){
+    if (challengeType !== 1 && challengeType !== 2){
+        return [];
+    }
+
+    const missing = [];
+    if (typeof environment.TextEncoder !== "function"){
+        missing.push(advice.textEncoder);
+    }
+    if (nativeCrypto && !environment.crypto?.subtle){
+        missing.push(advice.webCrypto);
+    }
+    if (challengeType === 2 && typeof environment.Worker !== "function"){
+        missing.push(advice.worker);
+    }
+    return missing;
+}

web/src/challange/challanger.js

@@ -1,3 +1,4 @@
+import {detectMissingCapabilities} from "./capabilities";
 import {getChallengeSolver} from "./challanges";
 import * as loader from "./loader.js";
 
@@ -33,6 +34,12 @@ export async function doChallenge(){
         const {t} = challenge;
         countdown = challenge.c;
 
+        const missing = detectMissingCapabilities(t);
+        if (missing.length){
+            loader.showCapabilities(missing);
+            throw new Error(`Required browser feature unavailable: ${missing.map(({name}) => name).join(", ")}`);
+        }
+
         /* @berghain:inline challenge-start */
 
         const [name, solver] = getChallengeSolver(t);

web/src/challange/loader.js

@@ -14,7 +14,39 @@ export function start(){
 
 export function showError(error){
     const errors = /** @type {HTMLDivElement} */ (document.querySelector(".error-container"));
-    errors.insertAdjacentHTML("beforeend", `<code>${error}</code>`);
+    if (!errors){
+        return;
+    }
+    const message = document.createElement("code");
+    message.textContent = error;
+    errors.append(message);
+}
+
+/**
+ * Show actionable advice for capabilities required by the issued challenge.
+ *
+ * @param {{name: string, message: string, fix: string}[]} missing
+ */
+export function showCapabilities(missing){
+    const container = document.getElementById("capability-errors");
+    if (!container){
+        return;
+    }
+
+    const summary = document.createElement("p");
+    summary.textContent = "This browser is missing features required by the current challenge:";
+
+    const list = document.createElement("ul");
+    for (const capability of missing){
+        const item = document.createElement("li");
+        const name = document.createElement("strong");
+        name.textContent = capability.name;
+        item.append(name, `: ${capability.message} ${capability.fix}`);
+        list.append(item);
+    }
+
+    container.replaceChildren(summary, list);
+    container.style.display = "block";
 }
 
 export function setChallengeInfo(text){

web/src/main.js

@@ -7,8 +7,10 @@ import {doChallenge} from "./challange/challanger";
         /* @berghain:inline init */
 
         if (!navigator.cookieEnabled){
-            const noCookie = document.getElementById("no-cookie");
-            noCookie.style.display = "block";
+            const cookieWarning = document.getElementById("cookie-warning");
+            if (cookieWarning){
+                cookieWarning.style.display = "block";
+            }
             return;
         }
 

web/src/style.scss

@@ -34,6 +34,19 @@
     position: absolute;
 }
 
+.capability-errors {
+    margin: .5em 0;
+    padding: .5em 1em;
+    border-left: 3px solid #b65f0a;
+    background-color: #fdf6ec;
+    text-align: left;
+
+    ul {
+        margin: .25em 0 0;
+        padding-left: 1.2em;
+    }
+}
+
 code {
     padding: 16px;
     overflow: auto;

web/test/capabilities.test.js

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {detectMissingCapabilities} from "../src/challange/capabilities.js";
+
+const completeEnvironment = {
+    TextEncoder: class {},
+    Worker: class {},
+    crypto: {subtle: {}},
+};
+
+test("does not probe capabilities unused by a no-op challenge", () => {
+    assert.deepEqual(detectMissingCapabilities(0, {
+        environment: {},
+        nativeCrypto: true,
+    }), []);
+});
+
+test("requires only text encoding for bundled-crypto POW", () => {
+    assert.deepEqual(detectMissingCapabilities(1, {
+        environment: completeEnvironment,
+        nativeCrypto: false,
+    }), []);
+
+    const missing = detectMissingCapabilities(1, {
+        environment: {},
+        nativeCrypto: false,
+    });
+    assert.deepEqual(missing.map(({name}) => name), ["Text encoding"]);
+});
+
+test("requires Web Crypto only in the native build", () => {
+    const missing = detectMissingCapabilities(1, {
+        environment: {TextEncoder: class {}},
+        nativeCrypto: true,
+    });
+    assert.deepEqual(missing.map(({name}) => name), ["Web Crypto"]);
+});
+
+test("requires a Worker only for worker POW", () => {
+    const environment = {...completeEnvironment, Worker: undefined};
+    const missing = detectMissingCapabilities(2, {
+        environment,
+        nativeCrypto: false,
+    });
+    assert.deepEqual(missing.map(({name}) => name), ["Web Workers"]);
+});