@bygghammar/cms-platform 0.80.1 → 0.90.0-m7.1

package/src/popups/media-bridge.tsx

@@ -0,0 +1,84 @@
+/**
+ * The CMS media library, offered to the popup builder.
+ *
+ * This is the whole bridge: the popup package asks a host to render a picker,
+ * and the host renders the same `MediaPickerDialog` every other CMS screen
+ * uses. Nothing is reimplemented — the library's browsing, searching and
+ * uploading all come along, because it is literally the same component.
+ *
+ * What crosses the boundary is a URL, a filename and (when the library knows
+ * one) alt text. The popup package never learns which storage provider the
+ * site uses, and never uploads anything itself.
+ */
+import type { ReactNode } from "react";
+
+import type {
+  HostMediaItem,
+  MediaPickerPort,
+} from "@bygghammar/lightweight-popup/adapters";
+
+import { MediaPickerDialog } from "../backoffice/inspectors/fields";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * What the picker hands back.
+ *
+ * Structural rather than the library's own type: the shape has grown fields
+ * over time and a popup needs three of them.
+ */
+type PickedItem = {
+  url?: unknown;
+  name?: unknown;
+  path?: unknown;
+  alt?: unknown;
+} & Record<string, any>;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+/**
+ * Turn one library item into the neutral shape the popup package stores.
+ *
+ * `url` is the stable public address the media library already serves to the
+ * site — the same value every other block stores — so a popup configured in
+ * one environment keeps working in the next. A signed or expiring link would
+ * render today and 404 later, which the package's own reference check refuses
+ * anyway.
+ */
+export function toHostMediaItem(item: PickedItem): HostMediaItem | null {
+  const src = text(item.url) ?? text(item.path);
+  if (src === undefined) return null;
+  const name = text(item.name);
+  const alt = text(item.alt);
+  return {
+    src,
+    ...(name === undefined ? {} : { name }),
+    ...(alt === undefined ? {} : { alt }),
+  };
+}
+
+/**
+ * The site's media library as a popup media port.
+ *
+ * Images only: a popup's picture is a picture, and offering video here would
+ * put a file in an `<img>` that cannot render it.
+ */
+export function cmsMediaPicker(): MediaPickerPort {
+  return {
+    renderPicker: ({ onPick, onClose }): ReactNode => (
+      <MediaPickerDialog
+        accept="image"
+        onPick={(item) => {
+          const media = toHostMediaItem(item as PickedItem);
+          // A library row with no address is not something to hand on; closing
+          // is honest, and the editor keeps whatever they had.
+          if (media !== null) onPick(media);
+          onClose();
+        }}
+        onClose={onClose}
+      />
+    ),
+  };
+}

package/src/popups/register.ts

@@ -0,0 +1,23 @@
+/**
+ * Registers the Popups module's loaders.
+ *
+ * Deliberately tiny and free of popup imports: a site calls this once, and
+ * nothing about the popup runtime — not the package, not its CSS, not the
+ * builder — is evaluated until the module is both enabled and hydrated. The
+ * `import()` calls below are ordinary local imports the host's bundler turns
+ * into separate chunks; nothing is fetched from a remote origin.
+ *
+ * An explicit function rather than a module-scope side effect: a host whose
+ * `sideEffects` field is an allowlist tree-shakes a bare
+ * `import "…/popups/register"` away, taking the registration with it, and the
+ * build still succeeds. That failure is silent — no popup ever appears.
+ */
+import {
+  registerModuleAdmin,
+  registerModuleRuntime,
+} from "../modules/public-runtime";
+
+export function registerPopupModule(): void {
+  registerModuleRuntime("popups", () => import("./runtime"));
+  registerModuleAdmin("popups", () => import("./admin"));
+}

package/src/popups/runtime.tsx

@@ -0,0 +1,94 @@
+/**
+ * The Popups module's public-site integration.
+ *
+ * Importing this file registers the popup runtime with the module host, so a
+ * site enables popups by importing it once and switching the module on. It is
+ * the only popup entry a public bundle may reach: the builder, the statistics
+ * screen and the validator all live behind `./popups/admin`.
+ *
+ * Everything CMS-shaped is bridged here — the site's forms, its routing, its
+ * design tokens — so neither the popup package nor the site has to know about
+ * the other.
+ */
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import type { ReactNode } from "react";
+import { useRouterState } from "@tanstack/react-router";
+import { PopupRuntime } from "@bygghammar/lightweight-popup/runtime";
+import type { RuntimeAdapters } from "@bygghammar/lightweight-popup/adapters";
+
+import { ManagedForm } from "../forms/FormRenderer";
+import { onFormSubmissionSuccess } from "../forms/success-listeners";
+import { siteConfig } from "../config/site-config";
+import { popupPublicHost } from "./host";
+
+/**
+ * Renders one of the site's own forms inside a popup.
+ *
+ * Success comes from the CMS form seam rather than from this component, which
+ * is what makes a honeypot rejection impossible to miscount: the form runtime
+ * only announces submissions the host actually stored.
+ */
+function PopupForm({
+  formKey,
+  onSuccess,
+}: {
+  formKey: string;
+  onSuccess: () => void;
+}): ReactNode {
+  const latest = useRef(onSuccess);
+  latest.current = onSuccess;
+
+  useEffect(
+    () =>
+      onFormSubmissionSuccess((event) => {
+        if (event.formKey === formKey) latest.current();
+      }),
+    [formKey],
+  );
+
+  return <ManagedForm formKey={formKey} />;
+}
+
+/**
+ * Paths the runtime never displays on.
+ *
+ * Derived from the site's configured backoffice path rather than a hardcoded
+ * `/kontoret`, plus the CMS preview routes — a popup over the editor's own
+ * live preview would end up in screenshots.
+ */
+function excludedPaths(): readonly string[] {
+  const base = siteConfig().backofficePath.replace(/\/+$/, "");
+  return [`${base}/**`, base, "/preview/**"];
+}
+
+export function PopupModuleRuntime(): ReactNode {
+  const path = useRouterState({ select: (state) => state.location.pathname });
+  const host = popupPublicHost();
+
+  const renderForm = useCallback(
+    ({ formKey, onSuccess }: { formKey: string; onSuccess: () => void }) => (
+      <PopupForm formKey={formKey} onSuccess={onSuccess} />
+    ),
+    [],
+  );
+
+  const adapters = useMemo<RuntimeAdapters>(
+    () => ({
+      configs: host.configs,
+      analytics: host.analytics,
+      forms: { renderForm },
+    }),
+    [host, renderForm],
+  );
+
+  return (
+    <PopupRuntime
+      path={path}
+      adapters={adapters}
+      excludedPaths={excludedPaths()}
+    />
+  );
+}
+
+// Default export so the module host can load this file lazily.
+export default PopupModuleRuntime;

package/src/server/popup-optin-trigger.ts

@@ -0,0 +1,111 @@
+/**
+ * Whether a popup outcome is a genuine opt-in worth delivering.
+ *
+ * One predicate, in one file, because getting it wrong is the difference
+ * between "we sent the customer's email to their CRM" and "we sent a stranger's
+ * empty form to their CRM". Every caller goes through here; nothing decides
+ * this inline.
+ *
+ * The rule: only a stored submission counts. The honeypot path answers
+ * `{ ok: true, skipped: true }` — a deliberate lie to a bot, which the form
+ * system returns so the bot believes it succeeded — and treating that as an
+ * opt-in would deliver junk and inflate every conversion figure. Everything
+ * else a popup can produce (a "yes" click on its own, a "no", a dismissal, a
+ * "maybe later") is a decision, not a submission.
+ *
+ * Pure and host-agnostic. Server-only by convention, but safe anywhere.
+ */
+
+/** What a form submit answers with. Deliberately loose: input is untrusted. */
+export interface SubmissionOutcome {
+  readonly ok?: unknown;
+  readonly skipped?: unknown;
+}
+
+export type OptInRefusal =
+  | "not-a-submission"
+  | "submission-failed"
+  | "honeypot-skipped"
+  | "preview"
+  | "test-mode";
+
+export type OptInDecision =
+  | { readonly deliver: true }
+  | { readonly deliver: false; readonly reason: OptInRefusal };
+
+export interface OptInContext {
+  /** The result the form system returned. */
+  readonly outcome: SubmissionOutcome | null | undefined;
+  /** True inside the builder preview, which performs nothing. */
+  readonly preview?: boolean;
+  /** A popup marked test mode records nothing and delivers nothing. */
+  readonly testMode?: boolean;
+  /**
+   * An administrator pressing "send a test delivery". The only way a test-mode
+   * popup ever produces a request, and it is labelled as a test in the payload.
+   */
+  readonly explicitTestDelivery?: boolean;
+}
+
+/**
+ * A genuine, stored submission — the only thing that may be delivered.
+ *
+ * `ok === true && skipped !== true`, checked structurally rather than by type
+ * assertion, because this value comes back across a request boundary and an
+ * unknown shape must fail closed.
+ */
+export function isGenuineSubmission(
+  outcome: SubmissionOutcome | null | undefined,
+): boolean {
+  if (outcome === null || outcome === undefined || typeof outcome !== "object")
+    return false;
+  return outcome.ok === true && outcome.skipped !== true;
+}
+
+export function shouldDeliverOptIn(context: OptInContext): OptInDecision {
+  // An explicit test delivery is an administrator action, not a visitor's, and
+  // carries no submission at all.
+  if (context.explicitTestDelivery === true) return { deliver: true };
+
+  if (context.preview === true) return { deliver: false, reason: "preview" };
+
+  const outcome = context.outcome;
+  if (
+    outcome === null ||
+    outcome === undefined ||
+    typeof outcome !== "object"
+  ) {
+    return { deliver: false, reason: "not-a-submission" };
+  }
+  if (outcome.skipped === true)
+    return { deliver: false, reason: "honeypot-skipped" };
+  if (outcome.ok !== true)
+    return { deliver: false, reason: "submission-failed" };
+
+  // Test mode is checked last so the reason reported is the most specific one:
+  // an administrator debugging a test-mode popup wants to know the submission
+  // itself was fine.
+  if (context.testMode === true) return { deliver: false, reason: "test-mode" };
+
+  return { deliver: true };
+}
+
+/**
+ * The fields an administrator chose, and nothing else.
+ *
+ * A submission holds everything the visitor typed. A destination receives only
+ * what was explicitly mapped — so adding a "personal number" field to a form
+ * never silently starts sending it to a third party. Unmapped keys, absent
+ * keys and non-string values are all dropped rather than coerced.
+ */
+export function selectMappedFields(
+  submitted: Readonly<Record<string, unknown>>,
+  mapping: readonly string[],
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const key of mapping) {
+    const value = submitted[key];
+    if (typeof value === "string" && value !== "") out[key] = value;
+  }
+  return out;
+}

package/src/server/popup-optin-webhook-core.ts

@@ -0,0 +1,363 @@
+/**
+ * Delivering a genuine popup opt-in to somebody else's system.
+ *
+ * Host-agnostic: the site supplies a privileged database client, the signing
+ * secret resolved from its own environment, and the submitted values it
+ * already holds. Everything about *how* the delivery is made and secured lives
+ * here so every site gets the same guarantees.
+ *
+ * The rules this file exists to enforce:
+ *
+ *   - It is sent only for a genuine, stored submission. A "yes" click, a
+ *     dismissal or a honeypot hit is not an opt-in and never reaches here —
+ *     the caller decides that, and `popup-optin-trigger.ts` is the one place
+ *     allowed to.
+ *   - The endpoint is re-validated on every hop, including redirects, so a
+ *     destination that passes review cannot later redirect into the private
+ *     network. `fetch` follows redirects invisibly, so redirects are followed
+ *     manually here — that is the only way to see each hop.
+ *   - The body is signed with HMAC-SHA256 over a timestamped string, so a
+ *     receiver can verify origin AND reject a replay.
+ *   - Only fields an administrator explicitly mapped are sent. Nothing else
+ *     from the submission, and nothing at all from the browser's headers.
+ *   - The secret never appears in a return value, an error, or a log line.
+ *
+ * Server-only. Never import from client code.
+ */
+
+import { checkWebhookUrl } from "./webhook-url-guard";
+
+export const POPUP_WEBHOOK_SCHEMA_VERSION = 1;
+
+/** Everything a delivery needs, with no database and no environment in sight. */
+export interface OptInWebhookInput {
+  readonly endpoint: string;
+  /** Resolved by the host from its own environment. Never read from the database. */
+  readonly signingSecret: string;
+  /** Stable id for this delivery. The receiver uses it to deduplicate. */
+  readonly eventId: string;
+  readonly occurredAt: string;
+  readonly campaign: {
+    readonly id: string;
+    readonly key: string;
+    readonly name: string;
+  };
+  readonly form: { readonly id: string; readonly key?: string };
+  /** Only the fields the administrator mapped. Already filtered by the caller. */
+  readonly fields: Readonly<Record<string, string>>;
+  readonly context: {
+    readonly pageUrl?: string | null;
+    readonly referrer?: string | null;
+    readonly utmSource?: string | null;
+    readonly device?: string | null;
+  };
+  /** A test delivery an administrator asked for, clearly marked as such. */
+  readonly test?: boolean;
+  readonly timeoutMs?: number;
+  readonly maxResponseBytes?: number;
+  readonly maxRedirects?: number;
+  /** Injected in tests. */
+  readonly fetchImpl?: typeof fetch;
+  readonly now?: () => number;
+}
+
+export type DeliveryOutcome = {
+  readonly ok: boolean;
+  readonly status?: number;
+  /** A category, never a raw upstream body — that could echo back anything. */
+  readonly errorCategory?:
+    | "blocked-endpoint"
+    | "timeout"
+    | "network"
+    | "http-error"
+    | "too-large"
+    | "too-many-redirects";
+  /** One sentence for an administrator. Never contains the secret. */
+  readonly error?: string;
+  readonly durationMs: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_BYTES = 64 * 1024;
+const DEFAULT_MAX_REDIRECTS = 3;
+
+/**
+ * A URL safe to record and show.
+ *
+ * Query strings routinely carry tokens, so only the origin and path are kept.
+ */
+export function safeUrl(raw: string | null | undefined): string | null {
+  if (raw == null || raw.trim() === "") return null;
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return null;
+  }
+}
+
+/** The versioned body. Changing its shape means bumping the schema version. */
+export function buildOptInPayload(
+  input: OptInWebhookInput,
+): Record<string, unknown> {
+  return {
+    schema_version: POPUP_WEBHOOK_SCHEMA_VERSION,
+    event_id: input.eventId,
+    event: input.test === true ? "popup.opt_in.test" : "popup.opt_in",
+    occurred_at: input.occurredAt,
+    campaign: {
+      id: input.campaign.id,
+      key: input.campaign.key,
+      name: input.campaign.name,
+    },
+    form:
+      input.form.key === undefined
+        ? { id: input.form.id }
+        : { id: input.form.id, key: input.form.key },
+    fields: input.fields,
+    context: {
+      page_url: safeUrl(input.context.pageUrl),
+      referrer: safeUrl(input.context.referrer),
+      utm_source: input.context.utmSource ?? null,
+      device: input.context.device ?? null,
+    },
+  };
+}
+
+/**
+ * The string that gets signed.
+ *
+ * The timestamp is inside the signed material, not merely a header beside it:
+ * signing the body alone would let anyone who captured one delivery replay it
+ * forever, because the signature would still verify.
+ */
+export function signingBase(timestamp: string, body: string): string {
+  return `${POPUP_WEBHOOK_SCHEMA_VERSION}.${timestamp}.${body}`;
+}
+
+export async function signBody(
+  secret: string,
+  timestamp: string,
+  body: string,
+): Promise<string> {
+  const { createHmac } = await import("node:crypto");
+  return createHmac("sha256", secret)
+    .update(signingBase(timestamp, body))
+    .digest("hex");
+}
+
+/**
+ * Read at most `limit` bytes of a response, then stop.
+ *
+ * A receiver that answers with a gigabyte would otherwise hold this server's
+ * memory hostage. Nothing is done with the body but the read has to be bounded.
+ */
+async function drainBounded(
+  response: Response,
+  limit: number,
+): Promise<boolean> {
+  const body = response.body;
+  if (body === null) return true;
+  const reader = body.getReader();
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return true;
+      total += value?.byteLength ?? 0;
+      if (total > limit) return false;
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+/**
+ * POST with every redirect hop re-validated.
+ *
+ * `redirect: "manual"` is what makes the guard meaningful: with the default
+ * `follow`, the runtime chases a 302 into the private network before any of
+ * this code sees it.
+ */
+async function postWithGuardedRedirects(
+  url: string,
+  init: RequestInit,
+  options: { fetchImpl: typeof fetch; maxRedirects: number; maxBytes: number },
+): Promise<
+  | { response: Response; oversize: boolean }
+  | { blocked: DeliveryOutcome["errorCategory"] }
+> {
+  let target = url;
+  for (let hop = 0; hop <= options.maxRedirects; hop += 1) {
+    const check = checkWebhookUrl(target);
+    if (!check.ok) return { blocked: "blocked-endpoint" };
+
+    const response = await options.fetchImpl(target, {
+      ...init,
+      redirect: "manual",
+    });
+
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      if (location === null) return { response, oversize: false };
+      // Resolve relative redirects against the hop we actually made.
+      target = new URL(location, target).toString();
+      continue;
+    }
+
+    const withinLimit = await drainBounded(response, options.maxBytes);
+    return { response, oversize: !withinLimit };
+  }
+  return { blocked: "too-many-redirects" };
+}
+
+/**
+ * Deliver one opt-in. Never throws.
+ *
+ * A delivery failure must not take down the request that produced it: the
+ * visitor already submitted the form, and their submission is stored whatever
+ * the receiver does.
+ */
+export async function deliverOptInWebhook(
+  input: OptInWebhookInput,
+): Promise<DeliveryOutcome> {
+  const now = input.now ?? Date.now;
+  const startedAt = now();
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const maxBytes = input.maxResponseBytes ?? DEFAULT_MAX_BYTES;
+  const maxRedirects = input.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+
+  const check = checkWebhookUrl(input.endpoint);
+  if (!check.ok) {
+    return {
+      ok: false,
+      errorCategory: "blocked-endpoint",
+      error: check.message,
+      durationMs: now() - startedAt,
+    };
+  }
+
+  const body = JSON.stringify(buildOptInPayload(input));
+  const timestamp = String(Math.floor(now() / 1000));
+  const signature = await signBody(input.signingSecret, timestamp, body);
+
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  );
+
+  try {
+    const result = await postWithGuardedRedirects(
+      check.url.toString(),
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "user-agent": "cms-platform-webhooks/1",
+          "x-webhook-event":
+            input.test === true ? "popup.opt_in.test" : "popup.opt_in",
+          "x-webhook-event-id": input.eventId,
+          // The receiver deduplicates on this. Retries of the same opt-in
+          // reuse the same value, which is what makes a retry safe.
+          "x-webhook-idempotency-key": input.eventId,
+          "x-webhook-timestamp": timestamp,
+          "x-webhook-signature": `v1=${signature}`,
+        },
+        body,
+        signal: controller.signal,
+      },
+      { fetchImpl, maxRedirects, maxBytes },
+    );
+
+    if ("blocked" in result) {
+      return {
+        ok: false,
+        errorCategory: result.blocked,
+        error:
+          result.blocked === "too-many-redirects"
+            ? "The endpoint redirected too many times."
+            : "The endpoint redirected to an address inside this server's network.",
+        durationMs: now() - startedAt,
+      };
+    }
+
+    const { response, oversize } = result;
+    if (oversize) {
+      return {
+        ok: false,
+        status: response.status,
+        errorCategory: "too-large",
+        error: "The endpoint's reply was too large.",
+        durationMs: now() - startedAt,
+      };
+    }
+    if (!response.ok) {
+      return {
+        ok: false,
+        status: response.status,
+        errorCategory: "http-error",
+        // Deliberately not the response body: it is attacker-influenced text
+        // that would end up in an administrator's screen and the logs.
+        error: `The endpoint answered ${response.status}.`,
+        durationMs: now() - startedAt,
+      };
+    }
+    return { ok: true, status: response.status, durationMs: now() - startedAt };
+  } catch (caught) {
+    const aborted =
+      caught instanceof Error &&
+      (caught.name === "AbortError" || caught.message.includes("aborted"));
+    return {
+      ok: false,
+      errorCategory: aborted ? "timeout" : "network",
+      error: aborted
+        ? "The endpoint did not answer in time."
+        : "The endpoint could not be reached.",
+      durationMs: now() - startedAt,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Retry schedule
+// ---------------------------------------------------------------------------
+
+export const MAX_DELIVERY_ATTEMPTS = 5;
+
+/** Which failures are worth trying again. */
+export function isRetryable(outcome: DeliveryOutcome): boolean {
+  if (outcome.ok) return false;
+  switch (outcome.errorCategory) {
+    case "timeout":
+    case "network":
+      return true;
+    case "http-error":
+      // 4xx means the receiver understood and refused: sending it again changes
+      // nothing. 5xx and 429 are the receiver's problem, and may pass.
+      return (
+        outcome.status === undefined ||
+        outcome.status >= 500 ||
+        outcome.status === 429
+      );
+    // A blocked endpoint, an oversized reply or a redirect loop are
+    // configuration faults. Retrying is just repeating the same mistake.
+    default:
+      return false;
+  }
+}
+
+/**
+ * Exponential backoff with a ceiling: 1m, 5m, 25m, 2h05.
+ *
+ * Returns `null` when the attempt budget is spent, which is the caller's signal
+ * to mark the delivery terminally failed and stop holding its payload.
+ */
+export function nextAttemptDelayMs(attempt: number): number | null {
+  if (attempt >= MAX_DELIVERY_ATTEMPTS) return null;
+  const minutes = 60_000;
+  return Math.min(minutes * 5 ** (attempt - 1), 4 * 60 * minutes);
+}