@cloudware-de/gatekeeper-widget 0.0.0-stage → 0.1.0

package/src/element/widget.ts

@@ -0,0 +1,982 @@
+/**
+ * Custom Element: Checkbox, Token, Startzeitpunkt, Hard-Timeout.
+ * Spec: specs/002-widget/tasks.md T-204 T-205 T-209 T-210
+ * Spec: specs/002-widget/spec.md §Öffentliches Custom-Element-API
+ * Spec: specs/002-widget/spec.md Pflichtumfang Start / Timeout / Token
+ * Spec: specs/002-widget/spec.md §Formular-Kanten
+ * Spec: specs/002-widget/spec.md §Öffentliches Custom-Element-API (template)
+ * Verfassung: Artikel 5, 6, 10. ADR-008.
+ */
+import { InstanceClientError, type RedeemSuccess } from "../client/instance.js";
+import type { Transport } from "../client/transport.js";
+import { LOAD_NOTICE } from "../copy/load-notice.js";
+import { EnvelopeIsolationError } from "../envelope/run.js";
+import { terminateTrackedWorkers } from "../runtime/workers.js";
+import {
+  HARD_TIMEOUT_MS,
+  TOKEN_TTL_MS,
+  isAbortError,
+  expiresAtOf,
+  isChallengeExpired,
+  issuedAtOf,
+  parseStartMode,
+  readSubmitHold,
+  type StartMode,
+} from "./start.js";
+import {
+  attestChallenge,
+  createBoundClient,
+  mergeRedeemBody,
+  readBaseUrl,
+  readSiteKey,
+  readWasmUrl,
+  type RedeemIssueContext,
+} from "./session.js";
+import { HONEYPOT_FIELD } from "./honeypot.js";
+import { applyTemplateToHost } from "./templates/host.js";
+import { combinedLookCss } from "./templates/sheets.js";
+import { isWasmOom } from "../pow/oom.js";
+import {
+  challengeExpiredMessage,
+  isWidgetUiState,
+  labelForHost,
+  missingTokenMessage,
+  type WidgetUiState,
+} from "./states.js";
+
+export { HONEYPOT_FIELD } from "./honeypot.js";
+
+const TAG = "gatekeep-widget";
+const DEFAULT_FIELD_NAME = "gatekeep-token";
+
+let nextBoxId = 0;
+
+function nextId(prefix: string): string {
+  nextBoxId += 1;
+  return `${prefix}-${nextBoxId}`;
+}
+
+export interface WidgetRedeemClient {
+  redeem(body: unknown): Promise<RedeemSuccess>;
+}
+
+export interface WidgetProgressDetail {
+  readonly progress: number;
+  readonly completed: number;
+  readonly total: number;
+}
+
+export interface WidgetPrepareHooks {
+  requestChallenge(request: {
+    hostname: string;
+    action: string;
+    cdata: string;
+  }): Promise<unknown>;
+  solve(
+    challenge: unknown,
+    ctx: {
+      onProgress: (detail: WidgetProgressDetail) => void;
+      signal: AbortSignal;
+      wasmUrl: string;
+    },
+  ): Promise<unknown>;
+  downgrade?(challenge: unknown, nowMs: number): Promise<unknown>;
+}
+
+export type DelayHandle = { cancel(): void };
+export type DelayFn = (callback: () => void, ms: number) => DelayHandle;
+
+export class WidgetRedeemError extends Error {
+  readonly errorCodes: readonly string[];
+
+  constructor(message: string, errorCodes: readonly string[]) {
+    super(message);
+    this.name = "WidgetRedeemError";
+    this.errorCodes = errorCodes;
+  }
+}
+
+function fieldNameOf(host: HTMLElement): string {
+  const name = host.getAttribute("name")?.trim();
+  if (name) {
+    return name;
+  }
+  const data = host.getAttribute("data-field-name")?.trim();
+  return data && data.length > 0 ? data : DEFAULT_FIELD_NAME;
+}
+
+function codesFromUnknown(err: unknown): string[] {
+  if (err instanceof InstanceClientError && err.errorCodes.length > 0) {
+    return [...err.errorCodes];
+  }
+  if (err instanceof WidgetRedeemError && err.errorCodes.length > 0) {
+    return [...err.errorCodes];
+  }
+  if (err instanceof EnvelopeIsolationError) {
+    return [err.code];
+  }
+  if (err !== null && typeof err === "object" && "errorCodes" in err) {
+    const codes = (err as { errorCodes: unknown }).errorCodes;
+    if (
+      Array.isArray(codes) &&
+      codes.length > 0 &&
+      codes.every((item): item is string => typeof item === "string")
+    ) {
+      return codes;
+    }
+  }
+  if (err instanceof Error && "code" in err && typeof err.code === "string" && err.code.length > 0) {
+    return [err.code];
+  }
+  return ["invalid_solution"];
+}
+
+function defaultDelay(callback: () => void, ms: number): DelayHandle {
+  const id = setTimeout(callback, ms);
+  return { cancel: () => clearTimeout(id) };
+}
+
+export class GatekeepWidget extends HTMLElement {
+  static readonly formAssociated = true;
+
+  static get observedAttributes(): readonly string[] {
+    return [
+      "label-unchecked",
+      "label-checked",
+      "missing-token",
+      "expired-challenge",
+      "submit-hold",
+      "template",
+    ];
+  }
+
+  #internals: ElementInternals | null = null;
+  #state: WidgetUiState = "idle";
+  #checkbox: HTMLInputElement | null = null;
+  #labelEl: HTMLLabelElement | null = null;
+  #hidden: HTMLInputElement | null = null;
+  #honeypot: HTMLInputElement | null = null;
+  #token: string | null = null;
+  #issuedAtMs: number | null = null;
+  #pendingSolution: unknown = undefined;
+  #redeemClient: WidgetRedeemClient | null = null;
+  #prepareHooks: WidgetPrepareHooks | null = null;
+  #transport: Transport | undefined;
+  #attestation: Uint8Array | null = null;
+  #inFlight: Promise<string> | null = null;
+  #prepareFlight: Promise<void> | null = null;
+  #nowMs: () => number = () => Date.now();
+  #delay: DelayFn = defaultDelay;
+  #timeoutHandle: DelayHandle | null = null;
+  #ttlHandle: DelayHandle | null = null;
+  #expiryHandle: DelayHandle | null = null;
+  #challengeExpired = false;
+  #submitHeld = false;
+  #abort: AbortController | null = null;
+  #challenge: unknown = undefined;
+  #issueContext: RedeemIssueContext | null = null;
+  #downgraded = false;
+  #sessionActive = false;
+  #form: HTMLFormElement | null = null;
+  #boundFormFocus = (event: Event): void => {
+    this.#onFormInteraction(event);
+  };
+  #boundFormKeydown = (event: Event): void => {
+    this.#onFormInteraction(event);
+  };
+  #boundFormSubmit = (event: Event): void => {
+    this.#onFormSubmit(event);
+  };
+  #boundInvalid = (): void => {
+    if (this.#holdEnabled()) {
+      this.#submitHeld = true;
+    }
+  };
+
+  constructor() {
+    super();
+    try {
+      this.#internals = this.attachInternals();
+    } catch {
+      this.#internals = null;
+    }
+    applyTemplateToHost(this);
+    const root = this.attachShadow({ mode: "open" });
+    root.innerHTML = `<style>
+${combinedLookCss()}</style>
+<div class="gk-root">
+<label class="gk">
+  <input class="gk-box" type="checkbox" />
+  <span class="gk-label"></span>
+</label>
+<p class="gk-load"></p>
+</div>`;
+    this.#checkbox = root.querySelector("input[type=checkbox]");
+    this.#labelEl = root.querySelector("label.gk");
+    const notice = root.querySelector(".gk-load");
+    const id = nextId("gk-box");
+    const noticeId = nextId("gk-load");
+    if (notice instanceof HTMLElement) {
+      notice.id = noticeId;
+      notice.textContent = LOAD_NOTICE;
+    }
+    if (this.#checkbox) {
+      this.#checkbox.id = id;
+      this.#checkbox.setAttribute("aria-describedby", noticeId);
+      this.#checkbox.addEventListener("click", (event) => {
+        event.preventDefault();
+        void this.#onRedeemGesture();
+      });
+      this.#checkbox.addEventListener("keydown", (event) => {
+        if (event.key === " " || event.key === "Enter") {
+          event.preventDefault();
+          if (event.key === " ") {
+            void this.#onRedeemGesture();
+          }
+        }
+      });
+    }
+    if (this.#labelEl) {
+      this.#labelEl.htmlFor = id;
+    }
+    this.addEventListener("invalid", this.#boundInvalid);
+    this.#ensureHoneypot();
+    this.#writeFormValue(null);
+    this.#render();
+  }
+
+  connectedCallback(): void {
+    this.#bindForm();
+    if (this.#startMode() === "auto") {
+      queueMicrotask(() => {
+        void this.#beginPrepare();
+      });
+    }
+  }
+
+  disconnectedCallback(): void {
+    this.#unbindForm();
+    this.#clearTimeout();
+    this.#clearExpiry();
+    terminateTrackedWorkers();
+    this.#abort?.abort();
+    this.#sessionActive = false;
+    this.#prepareFlight = null;
+  }
+
+  get uiState(): WidgetUiState {
+    return this.#state;
+  }
+
+  /**
+   * T-204: UI-Zustand setzen, damit ARIA-Labels prüfbar sind.
+   */
+  applyUiState(state: WidgetUiState): void {
+    if (!isWidgetUiState(state)) {
+      throw new TypeError(`unknown widget UI state: ${state}`);
+    }
+    this.#state = state;
+    this.#render();
+  }
+
+  get siteKey(): string {
+    return readSiteKey(this);
+  }
+
+  get baseUrl(): string {
+    return readBaseUrl(this);
+  }
+
+  get wasmUrl(): string {
+    return readWasmUrl(this);
+  }
+
+  setRedeemClient(client: WidgetRedeemClient | null): void {
+    this.#redeemClient = client;
+  }
+
+  setPrepareHooks(hooks: WidgetPrepareHooks | null): void {
+    this.#prepareHooks = hooks;
+  }
+
+  setTransport(transport: Transport | undefined): void {
+    this.#transport = transport;
+  }
+
+  setPendingSolution(solution: unknown): void {
+    this.#pendingSolution = solution;
+  }
+
+  setNowMs(nowMs: () => number): void {
+    this.#nowMs = nowMs;
+  }
+
+  setDelay(delay: DelayFn): void {
+    this.#delay = delay;
+  }
+
+  getResponse(): string | null {
+    if (this.#honeypotFilled()) {
+      return null;
+    }
+    if (this.#token === null || this.isExpired()) {
+      return null;
+    }
+    return this.#token;
+  }
+
+  isExpired(): boolean {
+    if (this.#token === null || this.#issuedAtMs === null) {
+      return true;
+    }
+    return this.#nowMs() - this.#issuedAtMs >= TOKEN_TTL_MS;
+  }
+
+  /**
+   * T-210: fehlt die Lösung, zuerst Challenge/PoW.
+   * Checkbox-Klick löst ein, wenn die Lösung schon da ist.
+   */
+  async solve(): Promise<string> {
+    await this.#beginPrepare();
+    return this.#redeemOnly();
+  }
+
+  reset(): void {
+    this.#clearTimeout();
+    this.#clearTtl();
+    this.#clearExpiry();
+    this.#challengeExpired = false;
+    this.#abort?.abort();
+    this.#abort = null;
+    this.#token = null;
+    this.#issuedAtMs = null;
+    this.#pendingSolution = undefined;
+    this.#inFlight = null;
+    this.#prepareFlight = null;
+    this.#challenge = undefined;
+    this.#issueContext = null;
+    this.#attestation = null;
+    this.#downgraded = false;
+    this.#sessionActive = false;
+    this.#submitHeld = false;
+    this.#writeFormValue(null);
+    this.applyUiState("idle");
+    this.dispatchEvent(
+      new CustomEvent("gatekeep:reset", { bubbles: true, composed: true }),
+    );
+  }
+
+  attributeChangedCallback(name: string): void {
+    if (name === "template") {
+      applyTemplateToHost(this);
+    }
+    this.#render();
+  }
+
+  #startMode(): StartMode {
+    return parseStartMode(this.getAttribute("start-mode"));
+  }
+
+  #holdEnabled(): boolean {
+    return readSubmitHold(this);
+  }
+
+  #bindForm(): void {
+    this.#unbindForm();
+    const form = this.closest("form");
+    this.#form = form;
+    form?.addEventListener("focusin", this.#boundFormFocus);
+    form?.addEventListener("keydown", this.#boundFormKeydown);
+    form?.addEventListener("submit", this.#boundFormSubmit);
+  }
+
+  #unbindForm(): void {
+    this.#form?.removeEventListener("focusin", this.#boundFormFocus);
+    this.#form?.removeEventListener("keydown", this.#boundFormKeydown);
+    this.#form?.removeEventListener("submit", this.#boundFormSubmit);
+    this.#form = null;
+  }
+
+  #onFormSubmit(event: Event): void {
+    if (this.getResponse() !== null) {
+      return;
+    }
+    event.preventDefault();
+    if (this.#holdEnabled()) {
+      this.#submitHeld = true;
+    }
+  }
+
+  #onFormInteraction(event: Event): void {
+    if (this.#startMode() !== "interaction") {
+      return;
+    }
+    if (event.composedPath().includes(this)) {
+      return;
+    }
+    void this.#beginPrepare();
+  }
+
+  #fieldName(): string {
+    return fieldNameOf(this);
+  }
+
+  #ensureHoneypot(): void {
+    if (this.#honeypot) {
+      return;
+    }
+    const input = document.createElement("input");
+    input.type = "text";
+    input.name = HONEYPOT_FIELD;
+    input.autocomplete = "off";
+    input.tabIndex = -1;
+    input.setAttribute("aria-hidden", "true");
+    input.setAttribute("data-gatekeep-honeypot", "1");
+    input.style.position = "absolute";
+    input.style.left = "-9999px";
+    input.style.width = "1px";
+    input.style.height = "1px";
+    input.style.overflow = "hidden";
+    input.style.clipPath = "inset(50%)";
+    input.style.border = "0";
+    input.style.padding = "0";
+    input.style.margin = "0";
+    this.append(input);
+    this.#honeypot = input;
+  }
+
+  #honeypotFilled(): boolean {
+    this.#ensureHoneypot();
+    const root = this.#form ?? this;
+    const fields = root.querySelectorAll(`input[name="${HONEYPOT_FIELD}"]`);
+    for (let i = 0; i < fields.length; i += 1) {
+      const node = fields.item(i);
+      if (node instanceof HTMLInputElement && node.value.trim() !== "") {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  #syncHidden(value: string): void {
+    const fieldName = this.#fieldName();
+    if (!this.#hidden) {
+      const input = document.createElement("input");
+      input.type = "hidden";
+      this.append(input);
+      this.#hidden = input;
+    }
+    this.#hidden.value = value;
+    if (this.#internals) {
+      this.#hidden.removeAttribute("name");
+      this.#hidden.setAttribute("form", "");
+    } else {
+      this.#hidden.name = fieldName;
+      this.#hidden.removeAttribute("form");
+    }
+  }
+
+  #writeFormValue(token: string | null): void {
+    const fieldName = this.#fieldName();
+    if (this.#internals) {
+      if (!this.hasAttribute("name")) {
+        this.setAttribute("name", fieldName);
+      }
+      this.#internals.setFormValue(token);
+    }
+    this.#syncHidden(token ?? "");
+    this.#syncValidity();
+  }
+
+  #syncValidity(): void {
+    const token = this.getResponse();
+    const message =
+      token === null
+        ? this.#challengeExpired
+          ? challengeExpiredMessage(this)
+          : missingTokenMessage(this)
+        : "";
+    if (this.#checkbox) {
+      this.#checkbox.setCustomValidity(message);
+    }
+    if (this.#hidden) {
+      this.#hidden.setCustomValidity(message);
+    }
+    if (!this.#internals) {
+      return;
+    }
+    try {
+      if (token === null) {
+        const box = this.#checkbox;
+        if (box) {
+          this.#internals.setValidity({ customError: true }, message, box);
+        } else {
+          this.#internals.setValidity({ customError: true }, message);
+        }
+      } else {
+        this.#internals.setValidity({});
+      }
+    } catch {
+      // Internals-Validity nicht verfügbar; setCustomValidity bleibt.
+    }
+  }
+
+  #flushHeldSubmit(): void {
+    if (!this.#submitHeld) {
+      return;
+    }
+    this.#submitHeld = false;
+    if (!this.#holdEnabled()) {
+      return;
+    }
+    const form = this.#form ?? this.closest("form");
+    if (!form) {
+      return;
+    }
+    if (typeof form.requestSubmit === "function") {
+      form.requestSubmit();
+    } else {
+      form.submit();
+    }
+  }
+
+  #emitError(errorCodes: readonly string[]): void {
+    this.dispatchEvent(
+      new CustomEvent("gatekeep:error", {
+        bubbles: true,
+        composed: true,
+        detail: { errorCodes: [...errorCodes] },
+      }),
+    );
+  }
+
+  #emitStart(): void {
+    this.dispatchEvent(
+      new CustomEvent("gatekeep:start", { bubbles: true, composed: true }),
+    );
+  }
+
+  #emitProgress(detail: WidgetProgressDetail): void {
+    this.dispatchEvent(
+      new CustomEvent("gatekeep:progress", {
+        bubbles: true,
+        composed: true,
+        detail,
+      }),
+    );
+  }
+
+  #clearTimeout(): void {
+    this.#timeoutHandle?.cancel();
+    this.#timeoutHandle = null;
+  }
+
+  #clearTtl(): void {
+    this.#ttlHandle?.cancel();
+    this.#ttlHandle = null;
+  }
+
+  #clearExpiry(): void {
+    this.#expiryHandle?.cancel();
+    this.#expiryHandle = null;
+  }
+
+  #pendingExpired(): boolean {
+    return (
+      isChallengeExpired(this.#challenge, this.#nowMs()) ||
+      isChallengeExpired(this.#pendingSolution, this.#nowMs())
+    );
+  }
+
+  #armChallengeExpiry(): void {
+    this.#clearExpiry();
+    const expiresAt = expiresAtOf(this.#challenge);
+    if (expiresAt === null) {
+      return;
+    }
+    const delay = expiresAt - this.#nowMs();
+    if (delay <= 0) {
+      return;
+    }
+    this.#expiryHandle = this.#delay(() => {
+      this.#expiryHandle = null;
+      void this.#onChallengeTtl();
+    }, delay);
+  }
+
+  #clearSessionForRetry(): void {
+    this.#clearTimeout();
+    this.#clearExpiry();
+    this.#abort?.abort();
+    this.#abort = null;
+    this.#pendingSolution = undefined;
+    this.#challenge = undefined;
+    this.#issueContext = null;
+    this.#attestation = null;
+    this.#downgraded = false;
+    this.#sessionActive = false;
+    this.#prepareFlight = null;
+  }
+
+  async #reissueAfterExpiry(): Promise<void> {
+    this.#challengeExpired = true;
+    this.applyUiState("timeout");
+    if (this.#pendingExpired() || this.#pendingSolution !== undefined) {
+      this.#emitError(["invalid_solution"]);
+      this.#clearSessionForRetry();
+    }
+    await this.#beginPrepare();
+  }
+
+  async #onChallengeTtl(): Promise<void> {
+    if (this.getResponse() !== null) {
+      return;
+    }
+    if (this.#inFlight) {
+      return;
+    }
+    this.#challengeExpired = true;
+    this.applyUiState("timeout");
+    this.#emitError(["invalid_solution"]);
+    this.#clearSessionForRetry();
+    await this.#beginPrepare();
+  }
+
+  #armTimeout(issuedAtMs: number): void {
+    this.#clearTimeout();
+    const delay = Math.max(0, issuedAtMs + HARD_TIMEOUT_MS - this.#nowMs());
+    this.#timeoutHandle = this.#delay(() => {
+      void this.#onHardTimeout();
+    }, delay);
+  }
+
+  #armTokenTtl(): void {
+    this.#clearTtl();
+    if (this.#issuedAtMs === null) {
+      return;
+    }
+    const delay = Math.max(0, this.#issuedAtMs + TOKEN_TTL_MS - this.#nowMs());
+    this.#ttlHandle = this.#delay(() => {
+      this.#ttlHandle = null;
+      this.reset();
+    }, delay);
+  }
+
+  async #beginPrepare(): Promise<void> {
+    if (this.#honeypotFilled()) {
+      return;
+    }
+    if (this.#sessionActive) {
+      return this.#prepareFlight ?? Promise.resolve();
+    }
+    if (this.#prepareFlight) {
+      return this.#prepareFlight;
+    }
+    if (this.#pendingSolution !== undefined && this.#pendingSolution !== null) {
+      return;
+    }
+    if (!this.#effectiveHooks()) {
+      return;
+    }
+    this.#sessionActive = true;
+    const run = this.#prepareOnce();
+    this.#prepareFlight = run;
+    try {
+      await run;
+    } finally {
+      if (this.#prepareFlight === run) {
+        this.#prepareFlight = null;
+      }
+    }
+  }
+
+  #boundClient() {
+    return createBoundClient(this, this.#transport);
+  }
+
+  #effectiveRedeemClient(): WidgetRedeemClient | null {
+    return this.#redeemClient ?? this.#boundClient();
+  }
+
+  #defaultHooks(): WidgetPrepareHooks | null {
+    const client = this.#boundClient();
+    if (!client) {
+      return null;
+    }
+    const wasmUrl = this.wasmUrl;
+    return {
+      requestChallenge: (request) => client.requestChallenge(request),
+      solve: async (challenge, ctx) => {
+        const { runSolve } = await import("../pow/run.js");
+        return runSolve(challenge as Parameters<typeof runSolve>[0], {
+          onProgress: ctx.onProgress,
+          wasmUrl,
+        });
+      },
+    };
+  }
+
+  #effectiveHooks(): WidgetPrepareHooks | null {
+    return this.#prepareHooks ?? this.#defaultHooks();
+  }
+
+  async #prepareOnce(): Promise<void> {
+    const hooks = this.#effectiveHooks();
+    if (!hooks) {
+      return;
+    }
+    this.#sessionActive = true;
+    this.#abort?.abort();
+    this.#abort = new AbortController();
+    const signal = this.#abort.signal;
+    const wasmUrl = this.wasmUrl;
+    this.#emitStart();
+    this.applyUiState("working");
+    try {
+      const issue = {
+        hostname: globalThis.location?.hostname || "localhost",
+        action: this.getAttribute("action") ?? "",
+        cdata: this.getAttribute("cdata") ?? "",
+      };
+      const challenge = await hooks.requestChallenge(issue);
+      if (signal.aborted) {
+        return;
+      }
+      this.#challenge = challenge;
+      this.#issueContext = { challenge, ...issue };
+      this.#attestation = await attestChallenge(challenge);
+      this.#downgraded = false;
+      this.#armTimeout(issuedAtOf(challenge, this.#nowMs()));
+      const solveStarted = this.#nowMs();
+      const solution = await hooks.solve(challenge, {
+        onProgress: (detail) => this.#emitProgress(detail),
+        signal,
+        wasmUrl,
+      });
+      if (signal.aborted) {
+        return;
+      }
+      this.#clearTimeout();
+      if (this.#issueContext === null) {
+        return;
+      }
+      const solveMs = Math.max(0, Math.round(this.#nowMs() - solveStarted));
+      this.#pendingSolution = mergeRedeemBody(solution, this.#attestation, {
+        ...this.#issueContext,
+        solveMs,
+      });
+      this.#challengeExpired = false;
+      this.#armChallengeExpiry();
+      if (this.#state === "working" || this.#state === "timeout") {
+        this.applyUiState("idle");
+      }
+    } catch (err) {
+      if (isAbortError(err) || signal.aborted) {
+        return;
+      }
+      const codes = codesFromUnknown(err);
+      if ((isWasmOom(err) || codes.includes("challenge_timeout")) && !this.#downgraded) {
+        await this.#onHardTimeout();
+        return;
+      }
+      this.#clearTimeout();
+      this.applyUiState("error");
+      this.#emitError(codes);
+    }
+  }
+
+  async #onHardTimeout(): Promise<void> {
+    this.#timeoutHandle = null;
+    if (this.#pendingSolution !== undefined && this.#pendingSolution !== null) {
+      return;
+    }
+    this.applyUiState("timeout");
+    if (this.#downgraded) {
+      this.#abort?.abort();
+      this.#emitError(["challenge_timeout"]);
+      return;
+    }
+    const hooks = this.#effectiveHooks();
+    const challenge = this.#challenge;
+    if (!hooks?.downgrade || challenge === undefined) {
+      this.#abort?.abort();
+      this.#downgraded = true;
+      this.#emitError(["challenge_timeout"]);
+      return;
+    }
+    this.#abort?.abort();
+    this.#abort = new AbortController();
+    const signal = this.#abort.signal;
+    this.#downgraded = true;
+    try {
+      const next = await hooks.downgrade(challenge, this.#nowMs());
+      if (signal.aborted) {
+        return;
+      }
+      this.#challenge = next;
+      if (this.#issueContext !== null) {
+        this.#issueContext = { ...this.#issueContext, challenge: next };
+      }
+      this.#armTimeout(issuedAtOf(next, this.#nowMs()));
+      this.#attestation = await attestChallenge(next);
+      const solveStarted = this.#nowMs();
+      const solution = await hooks.solve(next, {
+        onProgress: (detail) => this.#emitProgress(detail),
+        signal,
+        wasmUrl: this.wasmUrl,
+      });
+      if (signal.aborted) {
+        return;
+      }
+      this.#clearTimeout();
+      const context = this.#issueContext ?? {
+        challenge: next,
+        hostname: globalThis.location?.hostname || "localhost",
+      };
+      const solveMs = Math.max(0, Math.round(this.#nowMs() - solveStarted));
+      this.#pendingSolution = mergeRedeemBody(solution, this.#attestation, {
+        ...context,
+        solveMs,
+      });
+      this.#challengeExpired = false;
+      this.#armChallengeExpiry();
+      if (this.#state === "working" || this.#state === "timeout") {
+        this.applyUiState("idle");
+      }
+    } catch (err) {
+      if (isAbortError(err) || signal.aborted) {
+        return;
+      }
+      this.#clearTimeout();
+      this.applyUiState("timeout");
+      this.#emitError(
+        codesFromUnknown(err).includes("challenge_timeout")
+          ? ["challenge_timeout"]
+          : codesFromUnknown(err),
+      );
+    }
+  }
+
+  async #onRedeemGesture(): Promise<void> {
+    try {
+      if (this.#pendingExpired() || this.#challengeExpired) {
+        await this.#reissueAfterExpiry();
+      }
+      await this.#beginPrepare();
+      if (this.#pendingSolution === undefined || this.#pendingSolution === null) {
+        return;
+      }
+      await this.#redeemOnly();
+    } catch {
+      // Event trägt den Code; Gesture darf nicht als unhandled rejection enden.
+    }
+  }
+
+  async #redeemOnly(): Promise<string> {
+    if (this.#inFlight) {
+      return this.#inFlight;
+    }
+    if (this.#token !== null && !this.isExpired()) {
+      return this.#token;
+    }
+    const run = this.#redeemOnce();
+    this.#inFlight = run;
+    try {
+      return await run;
+    } finally {
+      if (this.#inFlight === run) {
+        this.#inFlight = null;
+      }
+    }
+  }
+
+  async #redeemOnce(): Promise<string> {
+    if (this.#pendingExpired()) {
+      await this.#reissueAfterExpiry();
+    }
+    return this.#acceptRedeem(true);
+  }
+
+  async #acceptRedeem(allowExpiryRetry: boolean): Promise<string> {
+    if (this.#honeypotFilled()) {
+      this.#token = null;
+      this.#writeFormValue(null);
+      this.#emitError(["missing_token"]);
+      throw new WidgetRedeemError("missing_token", ["missing_token"]);
+    }
+    const client = this.#effectiveRedeemClient();
+    const solution = this.#pendingSolution;
+    if (!client || solution === undefined || solution === null) {
+      this.#emitError(["missing_token"]);
+      throw new WidgetRedeemError("missing_token", ["missing_token"]);
+    }
+    this.applyUiState("working");
+    try {
+      const result = await client.redeem(solution);
+      this.#challengeExpired = false;
+      this.#clearExpiry();
+      this.#token = result.token;
+      this.#issuedAtMs = this.#nowMs();
+      this.#writeFormValue(result.token);
+      this.applyUiState("success");
+      this.#armTokenTtl();
+      this.dispatchEvent(
+        new CustomEvent("gatekeep:success", {
+          bubbles: true,
+          composed: true,
+          detail: { token: result.token },
+        }),
+      );
+      this.#flushHeldSubmit();
+      return result.token;
+    } catch (err) {
+      if (err instanceof WidgetRedeemError) {
+        throw err;
+      }
+      const codes = codesFromUnknown(err);
+      if (allowExpiryRetry && codes.includes("invalid_solution") && this.#pendingExpired()) {
+        await this.#reissueAfterExpiry();
+        return this.#acceptRedeem(false);
+      }
+      this.#challengeExpired = false;
+      this.applyUiState("error");
+      this.#emitError(codes);
+      throw err instanceof Error
+        ? err
+        : new WidgetRedeemError("redeem failed", codes);
+    }
+  }
+
+  #captionText(): string {
+    if (this.#challengeExpired && (this.#state === "timeout" || this.#state === "error")) {
+      return challengeExpiredMessage(this);
+    }
+    return labelForHost(this, this.#state);
+  }
+
+  #render(): void {
+    const box = this.#checkbox;
+    const label = this.#labelEl;
+    if (!box || !label) {
+      return;
+    }
+    const text = this.#captionText();
+    box.setAttribute("aria-label", text);
+    box.setAttribute("aria-busy", this.#state === "working" ? "true" : "false");
+    box.checked = this.#state === "success";
+    const caption = label.querySelector(".gk-label");
+    if (caption) {
+      caption.textContent = text;
+    }
+    if (this.#internals) {
+      this.#internals.ariaLabel = text;
+    }
+    this.#syncValidity();
+  }
+}
+
+export function defineGatekeepWidget(): void {
+  if (!customElements.get(TAG)) {
+    customElements.define(TAG, GatekeepWidget);
+  }
+}