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

package/src/backoffice/EditLock.tsx

@@ -0,0 +1,513 @@
+/**
+ * Editing locks in the browser.
+ *
+ * Three pieces, deliberately small:
+ *
+ * - `EditLockProvider` — the host mounts it once, around the backoffice, with
+ *   functions that call its own server endpoints. Nothing else needs wiring.
+ * - `useEditLock` — every editing screen calls it with the resource it has
+ *   open. It takes the lock, keeps it alive, and gives it back.
+ * - `EditLockBanner` — what the blocked editor sees.
+ *
+ * With no provider mounted the hook reports "not enforced" and every editor
+ * behaves exactly as it did before locks existed, which is what keeps an
+ * existing installation working while its host catches up.
+ *
+ * None of this is the protection itself. The server refuses the write; this is
+ * how a person finds out before typing for ten minutes.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+
+import {
+  asEditLockState,
+  claimEditSessionId,
+  DEFAULT_LOCK_TTL_SECONDS,
+  describeLock,
+  editSessionId,
+  heartbeatIntervalMs,
+  isBlocked,
+  lockHolderLabel,
+  secondsRemaining,
+  type EditLockRef,
+  type EditLockState,
+} from "../cms/edit-lock";
+
+export type { EditLockRef, EditLockState } from "../cms/edit-lock";
+
+/** What the host must provide, each call reaching its own server function. */
+export type EditLockApi = {
+  acquire: (
+    input: EditLockRef & { sessionId: string; ttlSeconds?: number },
+  ) => Promise<EditLockState>;
+  /** Defaults to `acquire`, which the server treats as a renewal. */
+  renew?: (
+    input: EditLockRef & { sessionId: string; ttlSeconds?: number },
+  ) => Promise<EditLockState>;
+  release: (input: EditLockRef & { sessionId: string }) => Promise<unknown>;
+  status?: (
+    input: EditLockRef & { sessionId?: string },
+  ) => Promise<EditLockState>;
+  /** Superadmin recovery for a lock whose owner is unreachable. */
+  steal?: (
+    input: EditLockRef & { sessionId: string; ttlSeconds?: number },
+  ) => Promise<EditLockState>;
+  /** Whether to offer the take-over button at all. */
+  canSteal?: boolean;
+  /** Lifetime to ask for. The server clamps it. */
+  ttlSeconds?: number;
+};
+
+/** The five things a host's lock endpoint has to answer. */
+export type EditLockAction = "acquire" | "renew" | "release" | "status" | "steal";
+
+/**
+ * Build the whole api from one call into the host's own transport.
+ *
+ * The five functions differ only in the word they send, so a host that writes
+ * them by hand writes the same thing five times. Give this a function that
+ * reaches its server however it already does — a server function, `fetch`, a
+ * react-query mutation — and it returns the api the provider wants:
+ *
+ * Keep the returned object stable (for example with `useMemo`) because its
+ * identity controls each editor's acquire/release effect.
+ *
+ * On the server, `editLockActionCore` is the matching half. Nothing here knows
+ * what the transport is or which database is behind it.
+ */
+export function createEditLockApi(
+  call: (
+    action: EditLockAction,
+    input: EditLockRef & { sessionId: string; ttlSeconds?: number },
+  ) => Promise<unknown>,
+  options: { canSteal?: boolean; ttlSeconds?: number } = {},
+): EditLockApi {
+  const send =
+    (action: EditLockAction) =>
+    async (input: EditLockRef & { sessionId?: string; ttlSeconds?: number }) =>
+      asEditLockState(
+        await call(action, { ...input, sessionId: input.sessionId ?? "" }),
+      );
+  return {
+    acquire: send("acquire"),
+    renew: send("renew"),
+    release: send("release"),
+    status: send("status"),
+    // Offered only when the host says so: the database refuses anyone but a
+    // superadmin, and a button that always fails is worse than no button.
+    ...(options.canSteal ? { steal: send("steal") } : {}),
+    canSteal: options.canSteal ?? false,
+    ...(options.ttlSeconds == null ? {} : { ttlSeconds: options.ttlSeconds }),
+  };
+}
+
+const ApiContext = createContext<EditLockApi | null>(null);
+
+export function EditLockProvider({
+  api,
+  children,
+}: {
+  api: EditLockApi | null;
+  children: ReactNode;
+}) {
+  return <ApiContext.Provider value={api}>{children}</ApiContext.Provider>;
+}
+
+export function useEditLockApi(): EditLockApi | null {
+  return useContext(ApiContext);
+}
+
+export type EditLockHandle = {
+  /** The editor may change things. False while identity is being checked or another holder blocks it. */
+  editable: boolean;
+  /** The editor must remain read-only, including during the identity handshake. */
+  blocked: boolean;
+  /** A lock is actually being kept. False with no provider, or on an installation without the migration. */
+  enforced: boolean;
+  state: EditLockState | null;
+  /** Pass to save calls as `editSessionId` so the server can tell it is us. */
+  sessionId: string;
+  /** One sentence for the person who is blocked. Empty when they are not. */
+  message: string;
+  holder: string;
+  /** Seconds until the blocking lock lapses on its own. */
+  expiresInSeconds: number | null;
+  busy: boolean;
+  error: string | null;
+  refresh: () => Promise<void>;
+  release: () => Promise<void>;
+  takeOver: () => Promise<void>;
+  canTakeOver: boolean;
+};
+
+export type UseEditLockOptions = {
+  /** Skip while the resource id is still loading, or in a read-only screen. */
+  enabled?: boolean;
+  ttlSeconds?: number;
+  /** Told when the lock is lost mid-edit, e.g. to warn before saving. */
+  onLost?: (state: EditLockState) => void;
+};
+
+const IDLE: EditLockState = { locked: false, held: false };
+
+/**
+ * One queue per resource and session, shared by every hook instance.
+ *
+ * Closing an editor and opening it again — a route change, or React's own
+ * double-invoked effects in development — releases from the old screen and
+ * acquires from the new one with the *same* session id. Those are two
+ * independent requests, and a release that happens to land second deletes a
+ * lock the editor believes it holds; nothing notices until the next heartbeat,
+ * a minute or so later, by which time somebody else may have taken it. The
+ * queue makes the server see the order the browser issued them in.
+ */
+const queues = new Map<string, Promise<unknown>>();
+
+function lockQueueKey(resourceType: string, resourceId: string, sessionId: string): string {
+  return [resourceType, resourceId, sessionId].join("\u0000");
+}
+
+function serialize<T>(key: string, work: () => Promise<T>): Promise<T> {
+  const previous = queues.get(key) ?? Promise.resolve();
+  // Run whether the one before succeeded or failed: a failed release must not
+  // strand every later call for this resource.
+  const result = previous.then(work, work);
+  const tail = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  queues.set(key, tail);
+  void tail.then(() => {
+    if (queues.get(key) === tail) queues.delete(key);
+  });
+  return result;
+}
+
+/**
+ * Hold one resource for as long as this screen is open.
+ *
+ * The session id lives in `sessionStorage`, so reloading the page keeps the
+ * lock the editor already had instead of locking them out of their own work,
+ * while a second tab gets its own id and is told about the first.
+ */
+export function useEditLock(
+  ref: { resourceType: string; resourceId?: string | null },
+  options: UseEditLockOptions = {},
+): EditLockHandle {
+  const api = useEditLockApi();
+  const { enabled = true, onLost } = options;
+  const ttlSeconds =
+    options.ttlSeconds ?? api?.ttlSeconds ?? DEFAULT_LOCK_TTL_SECONDS;
+
+  // Keep a valid id available for backward-compatible, provider-free screens.
+  // When enforcement is eligible the screen remains fenced until the live-
+  // document handshake has checked that sessionStorage was not copied.
+  const initialSessionId = useMemo(() => editSessionId(), []);
+  const [sessionId, setSessionId] = useState(initialSessionId);
+  const [sessionReady, setSessionReady] = useState(false);
+  const [stateResult, setStateResult] = useState<{
+    activation: object;
+    state: EditLockState;
+  } | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [errorResult, setErrorResult] = useState<{
+    activation: object;
+    message: string;
+  } | null>(null);
+
+  const resourceType = ref.resourceType;
+  const resourceId = ref.resourceId ?? "";
+  const eligible =
+    Boolean(api) && enabled && resourceType !== "" && resourceId !== "";
+  const active = eligible && sessionReady;
+  const queueKey = lockQueueKey(resourceType, resourceId, sessionId);
+  // A fresh token for every activation prevents A -> B -> A navigation from
+  // reviving A's old answer after its cleanup has already released that lock.
+  // It also fences provider, eligibility and TTL changes before effects run.
+  const activation = useMemo(
+    () => ({}),
+    [api, eligible, queueKey, ttlSeconds],
+  );
+  const state =
+    stateResult?.activation === activation ? stateResult.state : null;
+  const error =
+    errorResult?.activation === activation ? errorResult.message : null;
+
+  // Only the newest request may write state: a heartbeat that overtakes a
+  // take-over must not resurrect the answer it was already given.
+  const turn = useRef(0);
+  const lost = useRef(false);
+  const onLostRef = useRef(onLost);
+  onLostRef.current = onLost;
+
+  useEffect(() => {
+    let stopped = false;
+    void claimEditSessionId().then((claimed) => {
+      if (stopped) return;
+      setSessionId(claimed || initialSessionId);
+      setSessionReady(true);
+    });
+    return () => {
+      stopped = true;
+    };
+  }, [initialSessionId]);
+
+  const run = useCallback(
+    async (
+      call: (a: EditLockApi) => Promise<EditLockState>,
+      { showBusy = true }: { showBusy?: boolean } = {},
+    ) => {
+      if (!api || !active) return;
+      const mine = ++turn.current;
+      if (showBusy) setBusy(true);
+      try {
+        const next = await serialize(queueKey, () => call(api));
+        if (turn.current !== mine) return;
+        setStateResult({ activation, state: next });
+        setErrorResult(null);
+        if (isBlocked(next) && !lost.current) {
+          lost.current = true;
+          onLostRef.current?.(next);
+        } else if (!isBlocked(next)) {
+          lost.current = false;
+        }
+      } catch (e) {
+        if (turn.current !== mine) return;
+        // A lock we cannot reach must not stop anyone working. The server is
+        // still the authority on whether the save lands.
+        setErrorResult({
+          activation,
+          message: e instanceof Error ? e.message : String(e),
+        });
+      } finally {
+        // A newer non-busy heartbeat may supersede a manual request. Whichever
+        // turn wins must clear the older spinner as well as its own.
+        if (turn.current === mine) setBusy(false);
+      }
+    },
+    [api, active, queueKey, activation],
+  );
+
+  /* Take it, keep it, give it back. */
+  useEffect(() => {
+    if (!api || !active) {
+      setStateResult(null);
+      return;
+    }
+    let stopped = false;
+    const input = { resourceType, resourceId, sessionId, ttlSeconds };
+
+    const beat = (showBusy: boolean) => {
+      if (stopped) return;
+      void run((a) => (a.renew ?? a.acquire)(input), { showBusy });
+    };
+
+    void run((a) => a.acquire(input));
+    const timer = setInterval(
+      () => beat(false),
+      heartbeatIntervalMs(ttlSeconds),
+    );
+
+    // A backgrounded/bfcached tab may have lost the lock while its timers were
+    // suspended. Fence its stale answer before asking the server again.
+    const revalidate = () => {
+      setStateResult(null);
+      setErrorResult(null);
+      beat(false);
+    };
+    const onVisible = () => {
+      if (document.visibilityState === "visible") revalidate();
+    };
+    const onPageShow = (event: PageTransitionEvent) => {
+      if (event.persisted) revalidate();
+    };
+    let fullDocumentLeaving = false;
+    const onPageHide = (event: PageTransitionEvent) => {
+      fullDocumentLeaving = !event.persisted;
+    };
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("pageshow", onPageShow);
+    window.addEventListener("pagehide", onPageHide);
+
+    return () => {
+      stopped = true;
+      turn.current++;
+      clearInterval(timer);
+      document.removeEventListener("visibilitychange", onVisible);
+      window.removeEventListener("pageshow", onPageShow);
+      window.removeEventListener("pagehide", onPageHide);
+      // Leaving the editor frees the resource immediately rather than after
+      // the TTL. Full-document teardown deliberately relies on expiry instead:
+      // an old pagehide release can race a reload's acquire in another JS realm.
+      if (!fullDocumentLeaving) {
+        void serialize(queueKey, async () => api.release(input)).catch(() => {});
+      }
+    };
+  }, [api, active, resourceType, resourceId, sessionId, ttlSeconds, queueKey, run]);
+
+  const refresh = useCallback(async () => {
+    const input = { resourceType, resourceId, sessionId, ttlSeconds };
+    // A status reply saying "free" does not reserve anything. Acquire first,
+    // then enable editing only from the authoritative result of that attempt.
+    await run((a) => a.acquire(input));
+  }, [run, resourceType, resourceId, sessionId, ttlSeconds]);
+
+  const release = useCallback(async () => {
+    if (!api || !active) return;
+    turn.current++;
+    await serialize(queueKey, async () =>
+      api.release({ resourceType, resourceId, sessionId }),
+    ).catch(() => {});
+    setStateResult({ activation, state: IDLE });
+  }, [api, active, resourceType, resourceId, sessionId, queueKey, activation]);
+
+  const takeOver = useCallback(async () => {
+    await run((a) => {
+      if (!a.steal)
+        throw new Error("Taking over an editing lock is not available here.");
+      return a.steal({ resourceType, resourceId, sessionId, ttlSeconds });
+    });
+  }, [run, resourceType, resourceId, sessionId, ttlSeconds]);
+
+  const identityPending = eligible && !sessionReady;
+  const acquisitionPending = active && state === null && error === null;
+  const blocked =
+    identityPending || acquisitionPending || (active && isBlocked(state));
+  return {
+    editable: !blocked,
+    blocked,
+    enforced: active && state !== null && state.locked,
+    state,
+    sessionId,
+    message: blocked ? describeLock(state) : "",
+    holder: lockHolderLabel(state),
+    expiresInSeconds: blocked ? secondsRemaining(state) : null,
+    busy: busy || identityPending || acquisitionPending,
+    error,
+    refresh,
+    release,
+    takeOver,
+    canTakeOver:
+      active &&
+      isBlocked(state) &&
+      Boolean(api?.steal) &&
+      api?.canSteal !== false,
+  };
+}
+
+const BlockedContext = createContext(false);
+
+/**
+ * True when this part of the screen is inside a fence somebody else holds.
+ *
+ * A disabled `fieldset` stops form controls and buttons, but the browser
+ * happily goes on editing a `contenteditable` region inside one — which is
+ * every rich-text field in the page builder. Anything that edits outside a
+ * form control asks this and turns itself off.
+ */
+export function useEditLockBlocked(): boolean {
+  return useContext(BlockedContext);
+}
+
+/**
+ * Makes everything inside read-only while somebody else holds the lock.
+ *
+ * A disabled `fieldset` rather than an overlay: the content stays visible,
+ * selectable and scrollable — a blocked editor is meant to be able to *read* —
+ * while every control inside stops responding, including the drag handles,
+ * which are buttons. The server is what actually refuses the write; this only
+ * spares someone ten minutes of typing.
+ */
+export function EditLockFence({
+  lock,
+  children,
+  className = "",
+}: {
+  lock: EditLockHandle;
+  children: ReactNode;
+  className?: string;
+}) {
+  return (
+    <fieldset
+      disabled={lock.blocked}
+      aria-busy={lock.busy || undefined}
+      className={`min-w-0 border-0 p-0 m-0 ${lock.blocked ? "opacity-70" : ""} ${className}`.trim()}
+    >
+      <BlockedContext.Provider value={lock.blocked}>{children}</BlockedContext.Provider>
+    </fieldset>
+  );
+}
+
+/**
+ * What a blocked editor sees. Renders nothing when they are not blocked, so a
+ * screen can mount it unconditionally.
+ */
+export function EditLockBanner({
+  lock,
+  className = "",
+}: {
+  lock: EditLockHandle;
+  className?: string;
+}) {
+  // The fence also blocks during the short tab-identity handshake, but that is
+  // progress rather than another editor holding the resource and needs no
+  // read-only warning.
+  if (!lock.blocked || !isBlocked(lock.state)) return null;
+  const seconds = lock.expiresInSeconds;
+  return (
+    <div
+      role="status"
+      className={`border border-amber-300 bg-amber-50 p-4 text-sm text-amber-900 ${className}`.trim()}
+    >
+      <div className="text-[0.65rem] uppercase tracking-[0.22em] text-amber-700">
+        Read only
+      </div>
+      <p className="mt-2">{lock.message}</p>
+      {seconds !== null ? (
+        <p className="mt-1 text-xs text-amber-700">
+          {seconds > 0
+            ? `The lock lapses on its own in about ${Math.max(1, Math.round(seconds / 60))} min if it is not renewed.`
+            : "The lock has lapsed — check again to start editing."}
+        </p>
+      ) : null}
+      <div className="mt-3 flex flex-wrap gap-3">
+        <button
+          type="button"
+          onClick={() => void lock.refresh()}
+          disabled={lock.busy}
+          className="border border-amber-400 bg-white px-3 py-1 text-xs text-ink disabled:opacity-50"
+        >
+          {lock.busy ? "Checking…" : "Check again"}
+        </button>
+        {lock.canTakeOver ? (
+          <button
+            type="button"
+            onClick={() => {
+              const who = lock.holder;
+              if (
+                typeof window !== "undefined" &&
+                !window.confirm(
+                  `Take over editing from ${who}? Any unsaved work of theirs will be lost.`,
+                )
+              )
+                return;
+              void lock.takeOver();
+            }}
+            disabled={lock.busy}
+            className="border border-amber-400 bg-white px-3 py-1 text-xs text-ink disabled:opacity-50"
+          >
+            Take over
+          </button>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/backoffice/EmailSettingsView.tsx

@@ -1,6 +1,11 @@
 import { useEffect, useMemo, useState } from "react";
 import { toast } from "sonner";
 
+import {
+  describeSecretConfiguration,
+  type SecretsLocation,
+} from "../server/provider-secrets";
+
 export const PROVIDER_KINDS = ["smtp", "ses", "lovable", "mailgun", "http"] as const;
 export type ProviderKind = (typeof PROVIDER_KINDS)[number];
 
@@ -59,6 +64,12 @@ export type EmailSettingsDeps = {
   refreshLogs?: () => Promise<unknown> | void;
   /** Example addresses shown as placeholders — site specific. */
   placeholders?: { fromEmail?: string; notifyTo?: string };
+  /**
+   * Where this installation keeps its email credentials. Omitted, the screen
+   * describes the package's documented convention and says the deployment root
+   * differs per installation.
+   */
+  secretsLocation?: SecretsLocation;
 };
 
 const KIND_LABEL: Record<ProviderKind, string> = {
@@ -73,6 +84,85 @@ const input =
   "mt-1 w-full border border-ink/20 bg-white px-3 py-2 text-sm focus:border-sea focus:outline-none disabled:bg-ink/5";
 const lbl = "text-[0.65rem] uppercase tracking-[0.22em] text-ink/55";
 
+/**
+ * Where email credentials live on the server.
+ *
+ * Administrators keep asking where to put a password once they learn the CMS
+ * will not hold one, so the answer sits next to the question. It is deliberately
+ * value-free: variable *names* and file *locations* only. The names shown are
+ * the ones this screen already loads with each provider row, so nothing new is
+ * sent to the browser, and no value is read anywhere in this component.
+ */
+function SecretsLocationNote({
+  secrets,
+}: {
+  secrets: ReturnType<typeof describeSecretConfiguration>;
+}) {
+  const code =
+    "border border-ink/15 bg-white px-1.5 py-0.5 font-mono text-[0.7rem] text-ink";
+  return (
+    <section className="border border-ink/10 bg-ice/20 px-6 py-5">
+      <div className={lbl}>Where credentials are configured</div>
+
+      <p className="mt-2 text-sm text-ink/70">
+        {secrets.usesEnvFiles ? (
+          <>
+            Provider passwords and API keys are read from the server's environment, configured in{" "}
+            <code className={code}>{secrets.providerSecretsPath}</code>. System mail — account and
+            password messages — uses <code className={code}>{secrets.systemSecretName}</code>,
+            configured separately in <code className={code}>{secrets.systemEnvPath}</code>.
+          </>
+        ) : (
+          <>
+            This installation does not use environment files: provider passwords and API keys are
+            set as environment variables on the hosting platform. System mail — account and password
+            messages — uses <code className={code}>{secrets.systemSecretName}</code>.
+          </>
+        )}
+      </p>
+
+      {secrets.usesEnvFiles && !secrets.rootIsKnown ? (
+        <p className="mt-2 text-sm text-ink/60">
+          Those paths are relative to the deployment root, which differs per installation — the
+          directory the server runs from, the working directory of its service unit, or the root of
+          its container image. Your operator knows the absolute location.
+        </p>
+      ) : null}
+
+      {secrets.note ? <p className="mt-2 text-sm text-ink/60">{secrets.note}</p> : null}
+
+      {secrets.requiredNames.length > 0 ? (
+        <div className="mt-4">
+          <div className={lbl}>Variables these providers expect</div>
+          <ul className="mt-2 flex flex-wrap gap-2">
+            {secrets.requiredNames.map((name) => (
+              <li key={name}>
+                <code className={code}>{name}</code>
+              </li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+
+      {secrets.problems.length > 0 ? (
+        <ul className="mt-4 space-y-1 border border-amber-300 bg-amber-50 p-4 text-xs text-amber-800">
+          {secrets.problems.map((problem) => (
+            <li key={problem}>{problem}</li>
+          ))}
+        </ul>
+      ) : null}
+
+      <p className="mt-4 text-sm text-ink/70">
+        Enter only the <em>name</em> of a variable below — never the password or API key itself. A
+        credential saved as CMS content is stored in the database, travels in backups and page
+        exports, and is readable by anyone with CMS access. Secret names must match{" "}
+        <code className={code}>{secrets.namePattern}</code>. Values are never shown here, and this
+        screen has no way to read one.
+      </p>
+    </section>
+  );
+}
+
 /** Shared Email + providers screen. Data and actions come from the host. */
 export function EmailSettingsView({ deps }: { deps: EmailSettingsDeps }) {
   const { providers, isSuper } = deps;
@@ -125,6 +215,13 @@ export function EmailSettingsView({ deps }: { deps: EmailSettingsDeps }) {
     }
   };
 
+  // Names and locations only. No value is read here, and the browser's own
+  // environment is not the sending server's environment in any case.
+  const secrets = useMemo(
+    () => describeSecretConfiguration(providers, deps.secretsLocation),
+    [providers, deps.secretsLocation],
+  );
+
   const [editing, setEditing] = useState<EmailProviderLike | null>(null);
   const [creating, setCreating] = useState(false);
   const [duplicating, setDuplicating] = useState<EmailProviderLike | null>(null);
@@ -140,6 +237,8 @@ export function EmailSettingsView({ deps }: { deps: EmailSettingsDeps }) {
         </p>
       </div>
 
+      <SecretsLocationNote secrets={secrets} />
+
       {/* Providers list */}
       <section className="border border-ink/10 bg-white">
         <header className="flex items-center justify-between border-b border-ink/10 px-6 py-4">