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

package/dist/pow/worker.js

@@ -0,0 +1,43 @@
+/**
+ * Dedizierter Worker: nur Berechnung über @cloudware-de/gatekeeper-protocol.
+ * Spec: specs/002-widget/spec.md §WASM-Toolchain und Auslieferung
+ */
+import { GatekeepError, isErrorCode } from "@cloudware-de/gatekeeper-protocol";
+import { isWasmOom } from "./oom.js";
+import { solveChallenge } from "./solve.js";
+function post(event) {
+    postMessage(event);
+}
+onmessage = (event) => {
+    try {
+        const data = event.data;
+        if (data?.type !== "solve") {
+            return;
+        }
+        void solveChallenge(data.challenge, {
+            onProgress: (detail) => {
+                post({ type: "progress", ...detail });
+            },
+        })
+            .then((solution) => {
+            post({ type: "solution", solution });
+        })
+            .catch((error) => {
+            postSolveError(error);
+        });
+    }
+    catch (error) {
+        postSolveError(error);
+    }
+};
+function postSolveError(error) {
+    if (isWasmOom(error)) {
+        post({ type: "error", errorCodes: ["challenge_timeout"] });
+        return;
+    }
+    const code = error instanceof GatekeepError && isErrorCode(error.code)
+        ? error.code
+        : "internal_error";
+    post({ type: "error", errorCodes: [code] });
+}
+//# sourceMappingURL=worker.js.map

package/dist/pow/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../src/pow/worker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAE/E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,SAAS,IAAI,CAAC,KAAqB;IACjC,WAAW,CAAC,KAAK,CAAC,CAAC;AACrB,CAAC;AAED,SAAS,GAAG,CAAC,KAAoC,EAAE,EAAE;IACnD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACxB,IAAI,IAAI,EAAE,IAAI,KAAK,OAAO,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,KAAK,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE;YAClC,UAAU,EAAE,CAAC,MAAM,EAAE,EAAE;gBACrB,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YACxC,CAAC;SACF,CAAC;aACC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE;YACjB,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;QACvC,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,cAAc,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;IACP,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,cAAc,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;AACH,CAAC,CAAC;AAEF,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;QAC3D,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GACR,KAAK,YAAY,aAAa,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC;QACvD,CAAC,CAAC,KAAK,CAAC,IAAI;QACZ,CAAC,CAAC,gBAAgB,CAAC;IACvB,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC"}

package/dist/runtime/workers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lebende Worker: Track, Terminate, SecurityError.
+ * Spec: specs/002-widget/spec.md §Formular-Kanten T-212
+ * Envelope-Blob und PoW-Modul-Worker teilen dieselbe Menge.
+ */
+export declare function isSecurityError(error: unknown): boolean;
+export declare function trackWorker(worker: Worker): Worker;
+export declare function untrackWorker(worker: Worker): void;
+export declare function terminateTrackedWorkers(): number;
+export declare function trackedWorkerCount(): number;
+//# sourceMappingURL=workers.d.ts.map

package/dist/runtime/workers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.d.ts","sourceRoot":"","sources":["../../src/runtime/workers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKvD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAWhD;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}

package/dist/runtime/workers.js

@@ -0,0 +1,36 @@
+/**
+ * Lebende Worker: Track, Terminate, SecurityError.
+ * Spec: specs/002-widget/spec.md §Formular-Kanten T-212
+ * Envelope-Blob und PoW-Modul-Worker teilen dieselbe Menge.
+ */
+const live = new Set();
+export function isSecurityError(error) {
+    if (error instanceof DOMException) {
+        return error.name === "SecurityError";
+    }
+    return error instanceof Error && error.name === "SecurityError";
+}
+export function trackWorker(worker) {
+    live.add(worker);
+    return worker;
+}
+export function untrackWorker(worker) {
+    live.delete(worker);
+}
+export function terminateTrackedWorkers() {
+    const count = live.size;
+    for (const worker of live) {
+        try {
+            worker.terminate();
+        }
+        catch {
+            // bereits tot
+        }
+    }
+    live.clear();
+    return count;
+}
+export function trackedWorkerCount() {
+    return live.size;
+}
+//# sourceMappingURL=workers.js.map

package/dist/runtime/workers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.js","sourceRoot":"","sources":["../../src/runtime/workers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;AAE/B,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,KAAK,MAAM,MAAM,IAAI,IAAI,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,EAAE,CAAC;IACb,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@cloudware-de/gatekeeper-widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "private": false,
+  "description": "Cloudware Gatekeeper checkbox widget (Web Component). T-211 Artikel 8.",
+  "license": "GPL-2.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@cloudware-de/gatekeeper-protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "playwright": "1.63.0",
+    "tsx": "^4.20.5",
+    "typescript": "~5.9.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "node scripts/lint.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json && tsx --test tests/states.test.ts tests/session.test.ts tests/t203-copy-hold.test.ts tests/t204-checkbox.test.ts tests/t205-load-notice.test.ts tests/t206-client.test.ts tests/t207-pow.test.ts tests/t208-envelope.test.ts tests/t209-token-form.test.ts tests/t210-start-timeout.test.ts tests/t211-artikel8.test.ts tests/t212-attributes.test.ts tests/t212-edge-cases.test.ts tests/t213-challenge-expiry.test.ts tests/t214-honeypot.test.ts tests/t215-validity-oom.test.ts tests/t216-templates.test.ts"
+  }
 }

package/src/client/instance.ts

@@ -0,0 +1,140 @@
+/**
+ * POST challenge und redeem gegen die gesetzte Instanz-URL.
+ * Spec: specs/001-protocol-core/contracts/protocol-v1.md
+ * Spec: specs/002-widget/tasks.md T-206
+ * Redeem-Body (Option A): challenge + solution + hostname.
+ */
+import { fetchTransport, type Transport, type TransportResponse } from "./transport.js";
+import { instanceRouteUrl } from "./urls.js";
+
+export interface ChallengeIssueRequest {
+  readonly hostname: string;
+  readonly action?: string;
+  readonly cdata?: string;
+}
+
+export interface RedeemSuccess {
+  readonly token: string;
+  readonly expires_in: number;
+}
+
+export class InstanceClientError extends Error {
+  readonly status: number;
+  readonly errorCodes: readonly string[];
+  readonly retryAfter: number | undefined;
+
+  constructor(
+    message: string,
+    status: number,
+    errorCodes: readonly string[],
+    retryAfter?: number,
+  ) {
+    super(message);
+    this.name = "InstanceClientError";
+    this.status = status;
+    this.errorCodes = errorCodes;
+    this.retryAfter = retryAfter;
+  }
+}
+
+export interface InstanceClient {
+  readonly challengeUrl: string;
+  readonly redeemUrl: string;
+  requestChallenge(body: ChallengeIssueRequest): Promise<unknown>;
+  redeem(body: unknown): Promise<RedeemSuccess>;
+}
+
+export interface InstanceClientOptions {
+  readonly baseUrl: string;
+  readonly siteKey: string;
+  readonly transport?: Transport;
+}
+
+function readErrorCodes(body: unknown): string[] {
+  if (body === null || typeof body !== "object" || !("error-codes" in body)) {
+    return [];
+  }
+  const codes = (body as { "error-codes": unknown })["error-codes"];
+  if (!Array.isArray(codes)) {
+    return [];
+  }
+  return codes.filter((item): item is string => typeof item === "string");
+}
+
+function readRetryAfter(body: unknown): number | undefined {
+  if (body === null || typeof body !== "object" || !("retry-after" in body)) {
+    return undefined;
+  }
+  const value = (body as { "retry-after": unknown })["retry-after"];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function requireHostname(body: ChallengeIssueRequest): void {
+  if (typeof body.hostname !== "string" || body.hostname.trim() === "") {
+    throw new InstanceClientError("hostname is required", 0, ["malformed_encoding"]);
+  }
+}
+
+function requireRedeemSuccess(body: unknown): RedeemSuccess {
+  if (body === null || typeof body !== "object") {
+    throw new InstanceClientError("redeem response is not an object", 200, ["malformed_encoding"]);
+  }
+  const record = body as { token?: unknown; expires_in?: unknown };
+  if (typeof record.token !== "string" || record.token.length === 0) {
+    throw new InstanceClientError("redeem response missing token", 200, ["malformed_encoding"]);
+  }
+  if (typeof record.expires_in !== "number" || !Number.isFinite(record.expires_in)) {
+    throw new InstanceClientError("redeem response missing expires_in", 200, ["malformed_encoding"]);
+  }
+  return { token: record.token, expires_in: record.expires_in };
+}
+
+export function createInstanceClient(options: InstanceClientOptions): InstanceClient {
+  const challengeUrl = instanceRouteUrl(options.baseUrl, options.siteKey, "challenge");
+  const redeemUrl = instanceRouteUrl(options.baseUrl, options.siteKey, "redeem");
+  const transport = options.transport ?? fetchTransport;
+
+  async function post(url: string, body: unknown): Promise<TransportResponse> {
+    return transport({
+      url,
+      method: "POST",
+      body,
+      headers: {},
+    });
+  }
+
+  return {
+    challengeUrl,
+    redeemUrl,
+    async requestChallenge(body: ChallengeIssueRequest): Promise<unknown> {
+      requireHostname(body);
+      const payload: ChallengeIssueRequest = {
+        hostname: body.hostname,
+        ...(body.action !== undefined ? { action: body.action } : {}),
+        ...(body.cdata !== undefined ? { cdata: body.cdata } : {}),
+      };
+      const response = await post(challengeUrl, payload);
+      if (response.status === 200) {
+        return response.body;
+      }
+      throw new InstanceClientError(
+        "challenge request failed",
+        response.status,
+        readErrorCodes(response.body),
+        readRetryAfter(response.body),
+      );
+    },
+    async redeem(body: unknown): Promise<RedeemSuccess> {
+      const response = await post(redeemUrl, body);
+      if (response.status === 200) {
+        return requireRedeemSuccess(response.body);
+      }
+      throw new InstanceClientError(
+        "redeem request failed",
+        response.status,
+        readErrorCodes(response.body),
+        readRetryAfter(response.body),
+      );
+    },
+  };
+}

package/src/client/transport.ts

@@ -0,0 +1,55 @@
+/**
+ * Injizierbarer Transport. Default: fetch. Verify-Route nicht genutzt.
+ * Spec: specs/002-widget/tasks.md T-206
+ * Spec: specs/002-widget/spec.md §Adressierung
+ * Kein @cloudware-de/gatekeeper-protocol-Import — Fixture lädt dist/ ohne Import-Map.
+ */
+
+function encodeBase64Url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const byte of bytes) {
+    bin += String.fromCharCode(byte);
+  }
+  return btoa(bin).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+
+function jsonBody(body: unknown): string {
+  return JSON.stringify(body, (_key, value) => {
+    if (value instanceof Uint8Array) {
+      return encodeBase64Url(value);
+    }
+    return value;
+  });
+}
+export interface TransportRequest {
+  readonly url: string;
+  readonly method: "POST";
+  readonly body: unknown;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+export interface TransportResponse {
+  readonly status: number;
+  readonly body: unknown;
+}
+
+export type Transport = (request: TransportRequest) => Promise<TransportResponse>;
+
+export async function fetchTransport(request: TransportRequest): Promise<TransportResponse> {
+  const response = await fetch(request.url, {
+    method: request.method,
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+      ...request.headers,
+    },
+    body: jsonBody(request.body),
+  });
+  let body: unknown = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+  return { status: response.status, body };
+}

package/src/client/urls.ts

@@ -0,0 +1,38 @@
+/**
+ * Modul-1-Adressierung: {base}/{siteKey}/challenge|redeem.
+ * Spec: specs/001-protocol-core/spec.md §Adressierung
+ * Spec: specs/002-widget/spec.md §Adressierung
+ * Spec: specs/002-widget/tasks.md T-206
+ */
+export type InstanceRoute = "challenge" | "redeem";
+
+export class InstanceUrlError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InstanceUrlError";
+  }
+}
+
+export function instanceRouteUrl(
+  baseUrl: string,
+  siteKey: string,
+  route: InstanceRoute,
+): string {
+  if (siteKey.trim() === "") {
+    throw new InstanceUrlError("site-key is required");
+  }
+  let url: URL;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new InstanceUrlError("base-url is not a valid URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new InstanceUrlError("base-url must be http: or https:");
+  }
+  const basePath = url.pathname.replace(/\/+$/, "");
+  url.pathname = `${basePath}/${encodeURIComponent(siteKey)}/${route}`;
+  url.search = "";
+  url.hash = "";
+  return url.href;
+}

package/src/copy/load-notice.ts

@@ -0,0 +1,8 @@
+/**
+ * Sichtbarer Rechenlast-Hinweis (Artikel 5).
+ * Spec: specs/002-widget/tasks.md T-205
+ * Spec: specs/002-widget/spec.md §Pflichtumfang
+ * Gleicher Zweck wie README.md §Rechenlast.
+ */
+export const LOAD_NOTICE =
+  "Ihr Browser löst eine speicher- bzw. iterationsgebundene Aufgabe. Das ist Absicht (Kosten pro Angriffsversuch), kein Mining.";

package/src/element/honeypot.ts

@@ -0,0 +1,4 @@
+/**
+ * Adapter honeypot field. Not part of the instrumentation envelope.
+ */
+export const HONEYPOT_FIELD = "gatekeep-hp";

package/src/element/session.ts

@@ -0,0 +1,131 @@
+/**
+ * CE-Session: Attribute → Client, WASM-URL, Envelope.
+ * Spec: specs/002-widget/spec.md §Adressierung §WASM §Pflichtumfang
+ * T-212 Drift D1 D2 D3. Kein @cloudware-de/gatekeeper-protocol-Import.
+ */
+import { createInstanceClient, type InstanceClient } from "../client/instance.js";
+import type { Transport } from "../client/transport.js";
+import {
+  runDeliveredProgram,
+  type DeliveredProgram,
+  type IsolatedRunner,
+} from "../envelope/run.js";
+import { resolveWasmUrl } from "../pow/wasm-url.js";
+
+export interface AttributeHost {
+  getAttribute(name: string): string | null;
+}
+
+export function readSiteKey(host: AttributeHost): string {
+  return host.getAttribute("site-key")?.trim() ?? "";
+}
+
+export function readBaseUrl(host: AttributeHost): string {
+  return host.getAttribute("base-url")?.trim() ?? "";
+}
+
+export function readWasmUrl(host: AttributeHost, moduleUrl: string = import.meta.url): string {
+  return resolveWasmUrl(host.getAttribute("wasm-url") ?? "", moduleUrl);
+}
+
+export function createBoundClient(
+  host: AttributeHost,
+  transport?: Transport,
+): InstanceClient | null {
+  const siteKey = readSiteKey(host);
+  const baseUrl = readBaseUrl(host);
+  if (siteKey.length < 1 || baseUrl.length < 1) {
+    return null;
+  }
+  return createInstanceClient({
+    baseUrl,
+    siteKey,
+    ...(transport !== undefined ? { transport } : {}),
+  });
+}
+
+export function programFromChallenge(challenge: unknown): DeliveredProgram | null {
+  if (challenge === null || typeof challenge !== "object") {
+    return null;
+  }
+  const record = challenge as Record<string, unknown>;
+  const nested = record.instrumentationProgram ?? record.program;
+  if (nested !== null && typeof nested === "object") {
+    const program = nested as Record<string, unknown>;
+    if (typeof program.source === "string" && program.source.length > 0) {
+      return {
+        programId: String(program.programId ?? record.instrumentationProgramId ?? ""),
+        programVersion: String(program.programVersion ?? "v1"),
+        source: program.source,
+      };
+    }
+  }
+  if (typeof record.instrumentationSource === "string" && record.instrumentationSource.length > 0) {
+    return {
+      programId: String(record.instrumentationProgramId ?? ""),
+      programVersion: String(record.instrumentationProgramVersion ?? "v1"),
+      source: record.instrumentationSource,
+    };
+  }
+  return null;
+}
+
+export async function attestChallenge(
+  challenge: unknown,
+  runner?: IsolatedRunner,
+): Promise<Uint8Array | null> {
+  const program = programFromChallenge(challenge);
+  if (program === null) {
+    return null;
+  }
+  return runDeliveredProgram(program, runner !== undefined ? { runner } : {});
+}
+
+/**
+ * Option A: Redeem sendet Challenge + Solution + hostname (stateless MAC).
+ * Spec: specs/001-protocol-core/contracts/protocol-v1.md
+ * Spec: packages/server/src/handler.ts redeem
+ */
+export interface RedeemIssueContext {
+  readonly challenge: unknown;
+  readonly hostname: string;
+  readonly action?: string;
+  readonly cdata?: string;
+  /** Widget KDF wall time. Not PII. Server logs it only when GATEKEEP_POW_LOG=1. */
+  readonly solveMs?: number;
+}
+
+export function mergeRedeemBody(
+  solution: unknown,
+  attestation: Uint8Array | null,
+  context: RedeemIssueContext,
+): unknown {
+  if (typeof context.hostname !== "string" || context.hostname.trim() === "") {
+    throw new Error("hostname is required");
+  }
+  const extra: Record<string, unknown> = {
+    challenge: context.challenge,
+    hostname: context.hostname,
+  };
+  if (typeof context.action === "string" && context.action.length > 0) {
+    extra.action = context.action;
+  }
+  if (typeof context.cdata === "string" && context.cdata.length > 0) {
+    extra.cdata = context.cdata;
+  }
+  if (attestation !== null) {
+    extra.instrumentationEnvelope = { attestation };
+  }
+  if (
+    typeof context.solveMs === "number" &&
+    Number.isInteger(context.solveMs) &&
+    context.solveMs >= 0 &&
+    context.solveMs <= 120_000
+  ) {
+    extra.solveMs = context.solveMs;
+  }
+  if (solution !== null && typeof solution === "object" && !Array.isArray(solution)) {
+    return { ...solution, ...extra };
+  }
+  return { solution, ...extra };
+}

package/src/element/start.ts

@@ -0,0 +1,99 @@
+/**
+ * Startzeitpunkt und Hard-Timeout (ADR-008, 10 s).
+ * Spec: specs/002-widget/tasks.md T-210
+ * Spec: specs/002-widget/spec.md Pflichtumfang Start / Timeout
+ * Nicht aus @cloudware-de/gatekeeper-protocol importieren (T-204-Fixture).
+ */
+
+export const HARD_TIMEOUT_MS = 10_000;
+/** Artikel 6; nicht aus @cloudware-de/gatekeeper-protocol importieren (T-204-Fixture). */
+export const TOKEN_TTL_MS = 300_000;
+
+export type StartMode = "interaction" | "auto" | "click";
+
+export function parseStartMode(value: string | null): StartMode {
+  if (value === "auto") {
+    return "auto";
+  }
+  if (value === "click") {
+    return "click";
+  }
+  return "interaction";
+}
+
+const FALSEY_FLAG = /^(0|false|off|no)$/i;
+
+/**
+ * T-212 Submit-Hold: Attribut → window.GATEKEEP_SUBMIT_HOLD → true.
+ * Aus = kein requestSubmit nach Erfolg; Validity blockiert leeren Submit weiter.
+ */
+export function parseBoolFlag(value: string | boolean | null | undefined): boolean | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return true;
+  }
+  return !FALSEY_FLAG.test(trimmed);
+}
+
+export function parseSubmitHold(
+  attribute: string | null,
+  env: string | boolean | undefined,
+): boolean {
+  const fromAttr = parseBoolFlag(attribute);
+  if (fromAttr !== undefined) {
+    return fromAttr;
+  }
+  const fromEnv = parseBoolFlag(env);
+  if (fromEnv !== undefined) {
+    return fromEnv;
+  }
+  return true;
+}
+
+export function readSubmitHold(host: { getAttribute(name: string): string | null }): boolean {
+  const env = typeof window !== "undefined" ? window.GATEKEEP_SUBMIT_HOLD : undefined;
+  return parseSubmitHold(host.getAttribute("submit-hold"), env);
+}
+
+export function expiresAtOf(value: unknown): number | null {
+  if (value === null || typeof value !== "object") {
+    return null;
+  }
+  if ("expiresAt" in value) {
+    const raw = (value as { expiresAt: unknown }).expiresAt;
+    if (typeof raw === "number" && Number.isInteger(raw) && raw >= 0) {
+      return raw;
+    }
+  }
+  if ("challenge" in value) {
+    return expiresAtOf((value as { challenge: unknown }).challenge);
+  }
+  return null;
+}
+
+export function isChallengeExpired(value: unknown, nowMs: number): boolean {
+  const expiresAt = expiresAtOf(value);
+  return expiresAt !== null && nowMs >= expiresAt;
+}
+
+export function issuedAtOf(challenge: unknown, fallbackMs: number): number {
+  if (challenge !== null && typeof challenge === "object" && "issuedAt" in challenge) {
+    const value = (challenge as { issuedAt: unknown }).issuedAt;
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+      return value;
+    }
+  }
+  return fallbackMs;
+}
+
+export function isAbortError(err: unknown): boolean {
+  return err instanceof DOMException
+    ? err.name === "AbortError"
+    : err instanceof Error && err.name === "AbortError";
+}