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

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);
+}

package/src/server/provider-secrets.ts

@@ -17,6 +17,19 @@ export const SECRET_REF_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Environment variable used by the self-hosted system-mail path. */
 export const SYSTEM_SMTP_SECRET_NAME = "SMTP_PASSWORD";
 
+/**
+ * Where provider credentials are configured, relative to the deployment root.
+ *
+ * This is the convention the package documents, not a guarantee about a given
+ * server: the deployment root differs per installation (a container image, a
+ * systemd unit's WorkingDirectory, a platform's own environment panel), so a
+ * host that keeps its environment elsewhere passes its own location.
+ */
+export const DEFAULT_PROVIDER_SECRETS_FILE = "deploy/provider-secrets.env";
+
+/** Where the system-mail credential is configured, relative to the same root. */
+export const DEFAULT_SYSTEM_ENV_FILE = ".env";
+
 export type ProviderSecretRow = {
   id?: string | null;
   name?: string | null;
@@ -147,8 +160,8 @@ export function secretRefProblems(providers: ProviderSecretRow[]): string[] {
 }
 
 /**
- * Operator-facing, value-free report of what must go into
- * `deploy/provider-secrets.env`.
+ * Operator-facing, value-free report of what must go into the provider
+ * secrets file.
  */
 export function formatProviderSecretReport(
   providers: ProviderSecretRow[],
@@ -157,14 +170,97 @@ export function formatProviderSecretReport(
   const reqs = requiredProviderSecrets(providers, env);
   if (reqs.length === 0) return "No active email providers — no provider secrets are required.";
   const lines = [
-    "Provider secrets to configure in deploy/provider-secrets.env (names only):",
+    `Provider secrets to configure in ${DEFAULT_PROVIDER_SECRETS_FILE} (names only):`,
     ...reqs.map((r) => {
       const state = !r.valid ? "INVALID/MISSING NAME" : r.present ? "set" : "NOT SET";
       return `  ${(r.name ?? "(none)").padEnd(28)} ${state.padEnd(20)} ${r.provider}${r.kind ? ` (${r.kind})` : ""}`;
     }),
     "",
-    `System mail (account/password emails) uses ${SYSTEM_SMTP_SECRET_NAME} and is configured separately in .env.`,
+    `System mail (account/password emails) uses ${SYSTEM_SMTP_SECRET_NAME} and is ` +
+      `configured separately in ${DEFAULT_SYSTEM_ENV_FILE}.`,
     "Never paste secret values into chat, logs, PostgreSQL, Git or the migration package.",
   ];
   return lines.join("\n");
 }
+
+/* ------------------------------------------------------- configuration help */
+
+/**
+ * Where an installation keeps its email credentials.
+ *
+ * Every field is optional because the answer is genuinely per-installation.
+ * A host that ships the documented layout passes nothing; one that mounts its
+ * environment elsewhere passes the paths it uses; one running on a platform
+ * that injects environment variables with no file at all passes
+ * `usesEnvFiles: false` and a `note` naming where its operators set them.
+ */
+export type SecretsLocation = {
+  /** Provider credentials file, relative to the deployment root. */
+  providerSecretsFile?: string | null;
+  /** System-mail credential file, relative to the deployment root. */
+  systemEnvFile?: string | null;
+  /** Absolute deployment root, when the installation has a fixed one. */
+  deploymentRoot?: string | null;
+  /** False when the platform injects environment variables without files. */
+  usesEnvFiles?: boolean;
+  /** Extra operator-facing sentence, e.g. the name of a hosting panel. */
+  note?: string | null;
+};
+
+/** Value-free description of how credentials are configured on the server. */
+export type SecretsGuidance = {
+  /** True when credentials live in files this guidance can point at. */
+  usesEnvFiles: boolean;
+  /** Provider credentials file, joined to the deployment root when known. */
+  providerSecretsPath: string;
+  /** System-mail credential file, joined the same way. */
+  systemEnvPath: string;
+  /** True when the paths above are absolute rather than a relative convention. */
+  rootIsKnown: boolean;
+  /** Variable names the configured providers require. Names only. */
+  requiredNames: string[];
+  /** Active providers naming no secret, or naming an unusable one. */
+  problems: string[];
+  /** Variable holding the system-mail credential. */
+  systemSecretName: string;
+  /** The shape a secret name must have. */
+  namePattern: string;
+  note: string | null;
+};
+
+function joinPath(root: string | null | undefined, file: string): string {
+  const raw = typeof root === "string" ? root.trim() : "";
+  if (!raw) return file;
+  const base = raw.replace(/\/+$/, "");
+  // `/` is a valid deployment root, especially inside a container. Removing
+  // its only slash must not turn an absolute path back into a relative one.
+  return base ? `${base}/${file}` : `/${file.replace(/^\/+/, "")}`;
+}
+
+/**
+ * Describe where email credentials must be configured, for operators.
+ *
+ * Returns names and locations only. Secret *values* are never read here — this
+ * runs in the browser as well as on the server, and the environment it would
+ * read is not the sending server's environment anyway.
+ */
+export function describeSecretConfiguration(
+  providers: ProviderSecretRow[] = [],
+  location: SecretsLocation = {},
+): SecretsGuidance {
+  const usesEnvFiles = location.usesEnvFiles !== false;
+  const providerFile = location.providerSecretsFile?.trim() || DEFAULT_PROVIDER_SECRETS_FILE;
+  const systemFile = location.systemEnvFile?.trim() || DEFAULT_SYSTEM_ENV_FILE;
+  const root = location.deploymentRoot?.trim() || null;
+  return {
+    usesEnvFiles,
+    providerSecretsPath: joinPath(root, providerFile),
+    systemEnvPath: joinPath(root, systemFile),
+    rootIsKnown: Boolean(root),
+    requiredNames: requiredSecretNames(providers),
+    problems: secretRefProblems(providers),
+    systemSecretName: SYSTEM_SMTP_SECRET_NAME,
+    namePattern: SECRET_REF_NAME_RE.source,
+    note: location.note?.trim() || null,
+  };
+}