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

package/src/envelope/run.ts

@@ -0,0 +1,126 @@
+/**
+ * Envelope-Hülle: geliefertes Programm isoliert ausführen, Attestation zurück.
+ * Spec: specs/002-widget/tasks.md T-208
+ * Spec: specs/002-widget/spec.md §Pflichtumfang §Formular-Kanten
+ * ADR-012: Schnittstelle, kein Generator-Inhalt, keine Rohsignal-Persistenz.
+ */
+import { isSecurityError, trackWorker, untrackWorker } from "../runtime/workers.js";
+export interface DeliveredProgram {
+  readonly programId: string;
+  readonly programVersion: string;
+  readonly source: string;
+}
+
+export type IsolatedRunner = (program: DeliveredProgram) => Promise<Uint8Array>;
+
+export class EnvelopeIsolationError extends Error {
+  readonly code: "malformed_encoding" | "internal_error" | "unsupported_algorithm";
+
+  constructor(
+    code: "malformed_encoding" | "internal_error" | "unsupported_algorithm",
+    message: string,
+  ) {
+    super(message);
+    this.name = "EnvelopeIsolationError";
+    this.code = code;
+  }
+}
+
+export function requireAttestation(bytes: Uint8Array): Uint8Array {
+  if (bytes.byteLength < 1) {
+    throw new EnvelopeIsolationError("malformed_encoding", "attestation must not be empty");
+  }
+  return bytes;
+}
+
+function requireProgram(program: DeliveredProgram): void {
+  if (program.programId.trim() === "") {
+    throw new EnvelopeIsolationError("malformed_encoding", "programId must not be empty");
+  }
+  if (program.programVersion.trim() === "") {
+    throw new EnvelopeIsolationError("malformed_encoding", "programVersion must not be empty");
+  }
+  if (program.source.length < 1) {
+    throw new EnvelopeIsolationError("malformed_encoding", "program source must not be empty");
+  }
+}
+
+function readAttestation(data: unknown): Uint8Array {
+  if (data instanceof Uint8Array) {
+    return data;
+  }
+  if (data instanceof ArrayBuffer) {
+    return new Uint8Array(data);
+  }
+  if (data !== null && typeof data === "object" && "attestation" in data) {
+    return readAttestation((data as { attestation: unknown }).attestation);
+  }
+  throw new EnvelopeIsolationError("malformed_encoding", "program did not return attestation");
+}
+
+/**
+ * Browser-Default: Programm als Worker-Skript (kein eval, kein parent-Storage).
+ */
+export function workerRunner(program: DeliveredProgram, timeoutMs = 2000): Promise<Uint8Array> {
+  if (typeof Worker !== "function" || typeof Blob !== "function") {
+    return Promise.reject(new EnvelopeIsolationError("internal_error", "isolated worker is not available"));
+  }
+  return new Promise((resolve, reject) => {
+    const blob = new Blob([program.source], { type: "text/javascript" });
+    const url = URL.createObjectURL(blob);
+    let worker: Worker;
+    try {
+      worker = new Worker(url);
+    } catch (error) {
+      URL.revokeObjectURL(url);
+      if (isSecurityError(error)) {
+        reject(
+          new EnvelopeIsolationError(
+            "unsupported_algorithm",
+            "blob worker blocked by CSP",
+          ),
+        );
+        return;
+      }
+      reject(new EnvelopeIsolationError("internal_error", "isolated worker failed to start"));
+      return;
+    }
+    trackWorker(worker);
+    let timer: ReturnType<typeof setTimeout>;
+    const finish = (fn: () => void): void => {
+      clearTimeout(timer);
+      untrackWorker(worker);
+      worker.terminate();
+      URL.revokeObjectURL(url);
+      fn();
+    };
+    timer = setTimeout(() => {
+      finish(() => {
+        reject(new EnvelopeIsolationError("internal_error", "isolated program timed out"));
+      });
+    }, timeoutMs);
+    worker.onmessage = (event: MessageEvent<unknown>) => {
+      finish(() => {
+        try {
+          resolve(requireAttestation(readAttestation(event.data)));
+        } catch (error) {
+          reject(error);
+        }
+      });
+    };
+    worker.onerror = () => {
+      finish(() => {
+        reject(new EnvelopeIsolationError("internal_error", "isolated program failed"));
+      });
+    };
+  });
+}
+
+export async function runDeliveredProgram(
+  program: DeliveredProgram,
+  options: { readonly runner?: IsolatedRunner; readonly timeoutMs?: number } = {},
+): Promise<Uint8Array> {
+  requireProgram(program);
+  const runner = options.runner ?? ((item) => workerRunner(item, options.timeoutMs));
+  return requireAttestation(await runner(program));
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @cloudware-de/gatekeeper-widget öffentlicher Einstieg. Tag: gatekeep-widget.
+ * Spec: specs/002-widget/spec.md §Öffentliches Custom-Element-API
+ */
+import { defineGatekeepWidget } from "./element/widget.js";
+
+export {
+  createInstanceClient,
+  InstanceClientError,
+  type ChallengeIssueRequest,
+  type InstanceClient,
+  type InstanceClientOptions,
+  type RedeemSuccess,
+} from "./client/instance.js";
+export { fetchTransport, type Transport, type TransportRequest, type TransportResponse } from "./client/transport.js";
+export { InstanceUrlError, instanceRouteUrl, type InstanceRoute } from "./client/urls.js";
+export { LOAD_NOTICE } from "./copy/load-notice.js";
+export {
+  ARIA_LABELS,
+  CHALLENGE_EXPIRED_MESSAGE,
+  TOKEN_MISSING_MESSAGE,
+  WIDGET_UI_STATES,
+  challengeExpiredMessage,
+  isWidgetUiState,
+  labelForHost,
+  labelForState,
+  missingTokenMessage,
+  type WidgetUiState,
+} from "./element/states.js";
+export {
+  attestChallenge,
+  createBoundClient,
+  mergeRedeemBody,
+  programFromChallenge,
+  readBaseUrl,
+  readSiteKey,
+  readWasmUrl,
+  type RedeemIssueContext,
+} from "./element/session.js";
+export { HONEYPOT_FIELD } from "./element/honeypot.js";
+export {
+  TEMPLATE_COMPACT,
+  TEMPLATE_CONTRAST,
+  TEMPLATE_STANDARD,
+  WIDGET_TEMPLATES,
+  parseTemplate,
+  type WidgetTemplate,
+} from "./element/templates/names.js";
+export {
+  HARD_TIMEOUT_MS,
+  TOKEN_TTL_MS,
+  expiresAtOf,
+  isChallengeExpired,
+  parseStartMode,
+  parseSubmitHold,
+  readSubmitHold,
+  type StartMode,
+} from "./element/start.js";
+export {
+  isSecurityError,
+  terminateTrackedWorkers,
+  trackWorker,
+  trackedWorkerCount,
+  untrackWorker,
+} from "./runtime/workers.js";
+export {
+  GatekeepWidget,
+  WidgetRedeemError,
+  defineGatekeepWidget,
+  type DelayFn,
+  type DelayHandle,
+  type WidgetPrepareHooks,
+  type WidgetProgressDetail,
+  type WidgetRedeemClient,
+} from "./element/widget.js";
+
+defineGatekeepWidget();

package/src/pow/messages.ts

@@ -0,0 +1,21 @@
+/**
+ * Worker-Kanal: Challenge rein → Fortschritt → Solution raus.
+ * Spec: specs/002-widget/spec.md §WASM-Toolchain und Auslieferung
+ */
+import type { ChallengeParams, Solution } from "@cloudware-de/gatekeeper-protocol";
+
+export interface PowProgress {
+  readonly progress: number;
+  readonly completed: number;
+  readonly total: number;
+}
+
+export interface PowSolveRequest {
+  readonly type: "solve";
+  readonly challenge: ChallengeParams;
+}
+
+export type PowWorkerEvent =
+  | ({ readonly type: "progress" } & PowProgress)
+  | { readonly type: "solution"; readonly solution: Solution }
+  | { readonly type: "error"; readonly errorCodes: readonly string[] };

package/src/pow/oom.ts

@@ -0,0 +1,20 @@
+/**
+ * WASM-Alloc/OOM erkennen, ohne neuen Fehlercode.
+ * Spec: specs/001-protocol-core/tasks.md T-036
+ * Spec: specs/002-widget/spec.md Pflichtumfang Start / Timeout
+ */
+export function isWasmOom(error: unknown): boolean {
+  if (error instanceof RangeError) {
+    return true;
+  }
+  if (!(error instanceof Error) || error.name === "AbortError") {
+    return false;
+  }
+  if (error.name === "RuntimeError" || error.name === "WebAssembly.RuntimeError") {
+    return true;
+  }
+  const text = `${error.name} ${error.message}`.toLowerCase();
+  return /out of memory|\boom\b|cannot allocate|allocation failed|memory access out of bounds/.test(
+    text,
+  );
+}

package/src/pow/run.ts

@@ -0,0 +1,78 @@
+/**
+ * Worker-Standard, Hauptthread-Fallback ohne Worker.
+ * Spec: specs/002-widget/spec.md §WASM-Toolchain und Auslieferung
+ * Spec: specs/002-widget/tasks.md T-207
+ * Spec: specs/002-widget/spec.md §Formular-Kanten (SecurityError)
+ */
+import { GatekeepError, type ChallengeParams, type Solution } from "@cloudware-de/gatekeeper-protocol";
+import { isSecurityError, trackWorker, untrackWorker } from "../runtime/workers.js";
+import type { PowSolveRequest, PowWorkerEvent } from "./messages.js";
+import { solveChallenge, type SolveOptions } from "./solve.js";
+
+export function workerAvailable(): boolean {
+  return typeof Worker === "function";
+}
+
+function solveInWorker(challenge: ChallengeParams, options: SolveOptions): Promise<Solution> {
+  return new Promise((resolve, reject) => {
+    let worker: Worker;
+    try {
+      worker = new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    trackWorker(worker);
+    const finish = (fn: () => void): void => {
+      untrackWorker(worker);
+      worker.terminate();
+      fn();
+    };
+    const request: PowSolveRequest = { type: "solve", challenge };
+    worker.onmessage = (event: MessageEvent<PowWorkerEvent>) => {
+      const data = event.data;
+      if (data.type === "progress") {
+        options.onProgress?.({
+          progress: data.progress,
+          completed: data.completed,
+          total: data.total,
+        });
+        return;
+      }
+      if (data.type === "solution") {
+        finish(() => resolve(data.solution));
+        return;
+      }
+      const first = data.errorCodes[0];
+      const code =
+        first === "unsupported_algorithm" || first === "challenge_timeout"
+          ? first
+          : "internal_error";
+      finish(() => reject(new GatekeepError(code, "pow worker failed")));
+    };
+    worker.onerror = () => {
+      finish(() => reject(new Error("pow worker failed to start")));
+    };
+    worker.postMessage(request);
+  });
+}
+
+export async function runSolve(
+  challenge: ChallengeParams,
+  options: SolveOptions & { readonly preferWorker?: boolean } = {},
+): Promise<Solution> {
+  const preferWorker = options.preferWorker !== false;
+  if (preferWorker && workerAvailable()) {
+    try {
+      return await solveInWorker(challenge, options);
+    } catch (error) {
+      if (error instanceof GatekeepError && error.code === "unsupported_algorithm") {
+        throw error;
+      }
+      if (isSecurityError(error)) {
+        return solveChallenge(challenge, options);
+      }
+    }
+  }
+  return solveChallenge(challenge, options);
+}

package/src/pow/solve.ts

@@ -0,0 +1,136 @@
+/**
+ * Deterministische PoW-Lösung über @cloudware-de/gatekeeper-protocol (ADR-007).
+ * Spec: specs/002-widget/tasks.md T-207
+ * Spec: specs/001-protocol-core/spec.md#proof-of-work-deterministischer-modus-als-vorgabe
+ *
+ * keyPrefix ist kein Challenge-Feld (ADR-005). verifySolution prüft, dass
+ * der Counter das claimed derivedKey ergibt (eine KDF je Teillösung).
+ * Der ehrliche Client läuft `subCount × LEVEL_CONFIGS.counter` KDF-Runden
+ * (Kalibrierung: c=5/15/30, 32 MiB) — nicht `counter = index`.
+ * Password = nonce ‖ u64be(counter). Fehlendes WASM / unbekannte KDF →
+ * unsupported_algorithm, nie PBKDF2-Ersatz.
+ * Spec: packages/protocol/calibrate/measure.ts
+ * Spec: specs/001-protocol-core/spec.md#schwierigkeitsstufen-und-eskalation
+ */
+import {
+  decodeBase64Url,
+  deriveSubSolution,
+  GatekeepError,
+  isKdfAvailable,
+  lookupLevelParams,
+  type ChallengeParams,
+  type Solution,
+  type SubSolution,
+} from "@cloudware-de/gatekeeper-protocol";
+import { isWasmOom } from "./oom.js";
+import type { PowProgress } from "./messages.js";
+
+export interface SolveOptions {
+  readonly onProgress?: (detail: PowProgress) => void;
+  /** Von der CE-Kaskade (wasm-url → GATEKEEP_WASM_URL → import.meta.url). */
+  readonly wasmUrl?: string;
+}
+
+function asBytes(value: unknown, label: string): Uint8Array {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (typeof value === "string" && value.length > 0) {
+    return decodeBase64Url(value);
+  }
+  throw new GatekeepError("malformed_encoding", `${label} must be bytes or base64url`);
+}
+
+/**
+ * HTTP issue is JSON (base64url salt/nonce). Tests pass Uint8Arrays.
+ */
+export function hydrateIssuedChallenge(raw: unknown): ChallengeParams {
+  if (raw === null || typeof raw !== "object") {
+    throw new GatekeepError("malformed_encoding", "challenge must be an object");
+  }
+  const record = raw as Record<string, unknown>;
+  if (typeof record.id !== "string" || typeof record.algorithm !== "string") {
+    throw new GatekeepError("malformed_encoding", "challenge id/algorithm required");
+  }
+  return {
+    id: record.id,
+    siteKey: typeof record.siteKey === "string" ? record.siteKey : "",
+    algorithm: record.algorithm,
+    salt: asBytes(record.salt, "salt"),
+    nonce: asBytes(record.nonce, "nonce"),
+    cost: Number(record.cost),
+    level: Number(record.level),
+    subCount: Number(record.subCount),
+    issuedAt: Number(record.issuedAt),
+    expiresAt: Number(record.expiresAt),
+    instrumentationProgramId:
+      typeof record.instrumentationProgramId === "string" ? record.instrumentationProgramId : "",
+    downgraded: record.downgraded === true,
+  };
+}
+
+/**
+ * Search space for one sub-solution. Issued JSON `counter` wins;
+ * otherwise LEVEL_CONFIGS / FALLBACK via `lookupLevelParams`.
+ */
+export function searchSpaceFor(raw: unknown): number {
+  const record = raw !== null && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+  const issued = record.counter;
+  if (typeof issued === "number" && Number.isInteger(issued) && issued >= 1) {
+    return issued;
+  }
+  const algorithm = typeof record.algorithm === "string" ? record.algorithm : "";
+  const level = typeof record.level === "number" ? record.level : Number(record.level);
+  const configured = lookupLevelParams(algorithm, level);
+  if (configured !== undefined && Number.isInteger(configured.counter) && configured.counter >= 1) {
+    return configured.counter;
+  }
+  return 1;
+}
+
+export async function solveChallenge(
+  challenge: ChallengeParams | unknown,
+  options: SolveOptions = {},
+): Promise<Solution> {
+  const issued = hydrateIssuedChallenge(challenge);
+  const record = challenge as Record<string, unknown>;
+  const memoryCost = typeof record.memoryCost === "number" ? record.memoryCost : undefined;
+  const parallelism = typeof record.parallelism === "number" ? record.parallelism : undefined;
+  if (!isKdfAvailable(issued.algorithm)) {
+    throw new GatekeepError("unsupported_algorithm", `KDF not available: ${issued.algorithm}`);
+  }
+  const total = issued.subCount;
+  if (!Number.isInteger(total) || total < 1) {
+    throw new GatekeepError("incomplete_solution", "subCount must be a positive integer");
+  }
+  const search = searchSpaceFor(challenge);
+  const work = total * search;
+  const subSolutions: SubSolution[] = [];
+  let completed = 0;
+  for (let index = 0; index < total; index += 1) {
+    let derivedKey: Uint8Array | undefined;
+    let usedCounter = 0;
+    for (let counter = 0; counter < search; counter += 1) {
+      try {
+        derivedKey = await deriveSubSolution(issued, counter, { memoryCost, parallelism });
+      } catch (error) {
+        if (isWasmOom(error)) {
+          throw new GatekeepError("challenge_timeout", "wasm memory allocation failed");
+        }
+        throw error;
+      }
+      usedCounter = counter;
+      completed += 1;
+      options.onProgress?.({
+        progress: completed / work,
+        completed,
+        total: work,
+      });
+    }
+    if (derivedKey === undefined) {
+      throw new GatekeepError("incomplete_solution", "search space must be a positive integer");
+    }
+    subSolutions.push({ index, counter: usedCounter, derivedKey });
+  }
+  return { challengeId: issued.id, subSolutions };
+}

package/src/pow/wasm-url.ts

@@ -0,0 +1,27 @@
+/**
+ * WASM-Asset-Kaskade (Artikel 3). Kein Fremd-CDN.
+ * Spec: specs/002-widget/spec.md §WASM-Toolchain und Auslieferung
+ */
+export function resolveWasmUrl(
+  attribute?: string,
+  moduleUrl: string = import.meta.url,
+): string {
+  const fromAttr = attribute?.trim() ?? "";
+  if (fromAttr.length > 0) {
+    return fromAttr;
+  }
+  const fromWindow =
+    typeof window !== "undefined" ? window.GATEKEEP_WASM_URL?.trim() ?? "" : "";
+  if (fromWindow.length > 0) {
+    return fromWindow;
+  }
+  return new URL("./gatekeep.wasm", moduleUrl).href;
+}
+
+declare global {
+  interface Window {
+    GATEKEEP_WASM_URL?: string;
+    /** T-212 Hold. false / "0" / "false" / "off" / "no" schaltet Auto-Submit aus. */
+    GATEKEEP_SUBMIT_HOLD?: string | boolean;
+  }
+}

package/src/pow/worker.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 type { PowSolveRequest, PowWorkerEvent } from "./messages.js";
+import { isWasmOom } from "./oom.js";
+import { solveChallenge } from "./solve.js";
+
+function post(event: PowWorkerEvent): void {
+  postMessage(event);
+}
+
+onmessage = (event: MessageEvent<PowSolveRequest>) => {
+  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: unknown) => {
+        postSolveError(error);
+      });
+  } catch (error) {
+    postSolveError(error);
+  }
+};
+
+function postSolveError(error: unknown): void {
+  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] });
+}

package/src/runtime/workers.ts

@@ -0,0 +1,40 @@
+/**
+ * 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<Worker>();
+
+export function isSecurityError(error: unknown): boolean {
+  if (error instanceof DOMException) {
+    return error.name === "SecurityError";
+  }
+  return error instanceof Error && error.name === "SecurityError";
+}
+
+export function trackWorker(worker: Worker): Worker {
+  live.add(worker);
+  return worker;
+}
+
+export function untrackWorker(worker: Worker): void {
+  live.delete(worker);
+}
+
+export function terminateTrackedWorkers(): number {
+  const count = live.size;
+  for (const worker of live) {
+    try {
+      worker.terminate();
+    } catch {
+      // bereits tot
+    }
+  }
+  live.clear();
+  return count;
+}
+
+export function trackedWorkerCount(): number {
+  return live.size;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.