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

package/docs/EDIT-LOCKS.md

@@ -0,0 +1,213 @@
+# Editing locks: what a host has to wire
+
+Two administrators opening the same page used to be a silent race — whoever
+saved last won, and the other one's work disappeared without a message. The
+lock makes that a refusal instead: the second person sees who has the page and
+cannot type into it, and the server refuses the write even if they try.
+
+The package supplies all of it except three connections only the host can make.
+Until they are made every screen behaves exactly as it did before locks
+existed, which is what lets an installation upgrade the package first and the
+database afterwards.
+
+## 1. Run the migration
+
+`migrations/20260902090000_dc072b25-8467-46ae-aef3-0ccdf40aa7eb.sql` creates
+`public.cms_edit_locks` and five functions. It is safe to run more than once.
+It is ordinary PostgreSQL — a table, an index, grants, one RLS policy and four
+`SECURITY DEFINER` functions with a pinned `search_path`. A host that stores
+locks some other way can skip it and supply its own adapter instead; see
+[Storage](#storage).
+
+Until it runs, `assertEditable` sees "no such function" and lets every write
+through — an upgrade cannot break saving. After it runs, the server checks are
+available; the provider and save-path forwarding below are still required for
+per-tab UI locking.
+
+## 2. One server endpoint
+
+Every lock call goes through `editLockActionCore`, so the host writes one
+server function rather than five:
+
+```ts
+import { editLockActionCore, isEditLockAction } from "@bygghammar/cms-platform/server/edit-locks-core";
+import { editLockSchemas } from "@bygghammar/cms-platform/server/schemas";
+
+export const editLock = serverFn(async ({ data }) => {
+  if (!isEditLockAction(data.action)) throw new Error("Unknown lock action");
+  const input = editLockSchemas.acquire.parse(data);
+  return editLockActionCore(await authContext(), data.action, input);
+});
+```
+
+`authContext()` returns the lock storage for the signed-in user — see
+[Storage](#storage) for what that is. The lock functions run as that user, so
+`is_staff` and RLS apply exactly as they do everywhere else.
+
+## 3. One provider in the browser
+
+```tsx
+import { useMemo } from "react";
+import { createEditLockApi, EditLockProvider } from "@bygghammar/cms-platform/backoffice/EditLock";
+
+const lockApi = useMemo(
+  () => createEditLockApi(
+    (action, input) => editLock({ data: { action, ...input } }),
+    { canSteal: isSuperadmin },
+  ),
+  [editLock, isSuperadmin],
+);
+
+<EditLockProvider api={lockApi}>{backoffice}</EditLockProvider>
+```
+
+Mount it once, around the backoffice. Every editing screen finds it by itself.
+Keep the API object stable with `useMemo`: its identity controls the editors'
+acquire/release effects, so rebuilding it during each render would repeatedly
+release and reacquire their locks.
+
+`canSteal` only decides whether the take-over button is *offered*; the database
+function refuses anyone but a superadmin regardless, so offering it to an
+ordinary editor produces a button that always fails.
+
+Leave the api `null` — or mount no provider at all — and every screen reports
+"not enforced" and behaves as before.
+
+## 4. Pass the session id on to the saves
+
+The provider is what shows the banner. The session id is what makes the server
+able to tell *this* editor's save from someone else's, and it travels with the
+save, not with the lock.
+
+Each screen already puts `lock.sessionId` into the deps it calls. The host's
+job is to forward it to the matching core:
+
+| Screen | Host dep | Core | Resource |
+| --- | --- | --- | --- |
+| `PageBuilderView` | `save`, `rename`, `schedule`, `cancelPublication`, `restoreVersion` | `savePageVersionCore`, `renamePageCore`, `schedulePageVersionCore`, `cancelPagePublicationCore`, `restorePageVersionCore` | `page` / page id |
+| `GlobalSectionBuilderView` | `save`, `rename`, `setKind` | `saveGlobalSectionVersionCore`, `renameGlobalSectionCore`, `setGlobalSectionKindCore` | `global_section` / section id |
+| `SectionEditorView`, `NavigationView`, `ContactDetailsView` | `save` | `saveContentSectionCore` | `content_section` / section key |
+| `FormEditorView` | `saveForm`; pass `editSessionId` into its host `VersionHistory` too | `saveFormCore`, `restoreFormVersionCore` | `form` / form id |
+| `FormSettingsView` | `saveDefaults`; forward the whole `data` object, or destructure its `editSessionId` into the core's third argument | `saveFormDefaultsCore` | `form_defaults` / `form_settings` |
+| `PageSeoPanelView` | `onSave(form, editSessionId)`, `onReset(editSessionId)` | `savePageSeoCore`, `deletePageSeoOverrideCore` | `page_seo` / `pageKey` |
+
+The cores and schemas accept `editSessionId` as an optional field so an
+unwired/unmigrated host keeps its old behaviour while no lock exists. Once a
+resource has a live lock, every protected write requires the matching session
+id, including writes by another tab of the same user. Forward it on every path
+in the table; omission is not a bypass.
+
+`PageSeoPanelView` additionally needs `pageKey`. Without it the SEO panel has
+no resource to lock and stays unlocked, even with everything else wired.
+
+## Storage
+
+`editLockActionCore` and `assertEditable` never touch a database themselves.
+Every read and write goes through `EditLockAdapter`
+(`@bygghammar/cms-platform/server/edit-lock-adapter`), five methods over the
+domain operations and nothing else:
+
+```ts
+type EditLockAdapter = {
+  assertStaff(): Promise<void>;
+  acquire(input: EditLockRef & { sessionId: string; ttlSeconds: number; steal: boolean }): Promise<EditLockState>;
+  status(input: EditLockRef & { sessionId: string | null }): Promise<EditLockState>;
+  release(input: EditLockRef & { sessionId: string }): Promise<boolean>;
+  list(): Promise<EditLockRow[]>;
+};
+```
+
+The context a core takes is `{ editLocks: <adapter> }`. Nothing in the contract
+names a driver, a client library or a wire format, so a self-hosted application
+on ordinary PostgreSQL implements it with the SQL it already writes:
+
+```ts
+import type { EditLockAdapter } from "@bygghammar/cms-platform/server/edit-lock-adapter";
+import { EditLockNotInstalledError } from "@bygghammar/cms-platform/server/edit-lock-adapter";
+import { asEditLockState } from "@bygghammar/cms-platform/cms/edit-lock";
+
+const MISSING = new Set(["42883", "42P01"]); // no such function, no such table
+
+export function editLockStorage(pool: Pool, userId: string): EditLockAdapter {
+  const query = async (text: string, values: unknown[]) => {
+    try {
+      return await pool.query(text, values);
+    } catch (error) {
+      if (MISSING.has(error.code)) throw new EditLockNotInstalledError();
+      throw error;
+    }
+  };
+  return {
+    async acquire(input) {
+      const { rows } = await query(
+        "SELECT public.cms_acquire_edit_lock($1, $2, $3, $4, $5) AS state",
+        [input.resourceType, input.resourceId, input.sessionId, input.ttlSeconds, input.steal],
+      );
+      return asEditLockState(rows[0]?.state);
+    },
+    // status, release, list and assertStaff in the same shape
+  };
+}
+```
+
+Two rules an adapter has to honour, whatever it is built on:
+
+- **`acquire` must be one atomic statement.** Two editors opening the same page
+  at the same instant have to contend on a single unique index so exactly one
+  wins. Read-then-write leaves a window in which both do.
+- **`sessionId` is a bearer token.** It goes in and is never returned. Knowing
+  another tab's session id is enough to save as its holder, so no read may
+  include it — not `status`, not `list`.
+
+Whether the storage runs on a stored function, plain SQL in the adapter, or a
+service of its own is the host's decision. A PostgREST-shaped host that already
+builds `{ supabase: { rpc }, userId, claims }` for its other cores can keep
+passing exactly that: `createSupabaseEditLockAdapter` is applied for it
+automatically, and the migration's functions are the storage.
+
+## What the server does with it
+
+`assertEditable` sits before each protected write. A write from another session
+throws `EditLockedError`. On the server it has `error.code === "edit_locked"` and
+`error.state`. TanStack Start serializes only an Error's message, so the message
+also begins with `edit_locked:` and `isEditLockedError()` recognises either
+form after transport. Do not replace that failure with a success response.
+
+This is a cooperative preflight lock, not a transaction-wide database fence.
+Expiry, a new acquisition, a superadmin steal, or an explicit release could
+land between the status preflight and a later PostgREST mutation. Strict
+transactional exclusion would require each mutation and its lock check in one
+database RPC, or a fencing token checked by the write itself.
+
+The per-tab session id is a bearer value and is never returned by a lock
+status/acquire response. Authenticated staff have column-level read access to
+the operational lock fields but not `session_id`; the administrative list RPC
+omits that column. This prevents a blocked browser from reading the
+holder's token and replaying it in a save.
+
+Modern browsers also hold an exclusive Web Lock for that bearer value before
+the first server acquire. This detects a duplicated tab even when the original
+is frozen. Browsers without Web Locks fall back to a short BroadcastChannel
+handshake. That fallback is best-effort because a frozen source tab can answer
+too late; without either primitive there is no duplicate-tab signal at all.
+Multi-user locking remains enforced in either case.
+
+## Choosing the lifetime
+
+A lock lasts 120 seconds by default and is renewed every 40. A browser that
+crashes therefore frees the page about two minutes later, with no cleanup job
+anywhere. Pass `ttlSeconds` to `createEditLockApi` to change it; the database
+clamps to 15–3600 whatever it is told.
+
+Leaving an editor through client-side navigation releases immediately. Closing
+or reloading the whole document relies on the TTL: firing a release from the
+old document can arrive after the reload has already reacquired with the same
+session and delete its new lock. A restored/backgrounded page stays fenced
+until its catch-up renewal confirms it still holds the resource.
+
+## Recovering a stuck lock
+
+`listEditLocksCore` returns every live lock, and `steal` takes one — superadmin
+only, enforced in the database. Neither is needed for the feature to work; they
+are for the afternoon somebody's laptop dies mid-edit and two minutes is too
+long to wait.

package/docs/POPUPS.md

@@ -0,0 +1,102 @@
+# Popups: what this package supplies
+
+`@bygghammar/lightweight-popup` is deliberately host-agnostic. It knows nothing
+about Supabase, about this CMS, or about any particular site. Everything it
+needs from the outside arrives through ports.
+
+This package is the adapter that fills those ports with the CMS's own systems,
+so a site gets a working popup builder by registering one module instead of
+reimplementing a media library, a form renderer and a page picker.
+
+## The bridges
+
+| Port | Filled with | File |
+| --- | --- | --- |
+| `MediaPickerPort` | The CMS media library dialog | `src/popups/media-bridge.tsx` |
+| `FormRenderPort` | The CMS form renderer | `src/popups/cms-bridges.ts` |
+| `PagePickerPort` | The CMS page list | `src/popups/cms-bridges.ts` |
+| `OptInDestinationAdminPort` | The host's webhook server functions | `src/popups/destinations.tsx` |
+
+All of them are assembled in `src/popups/admin.tsx`. **An unfilled port is not
+an integration.** `cmsMediaPicker` existed for weeks and was never placed on the
+adapters object, so `adapters.media` was permanently `undefined`, the builder
+took its no-picker fallback branch, and every administrator pasted storage URLs
+by hand. The failure was invisible because the fallback is a legitimate state
+for a host without a media library.
+
+`tests/popup-media-bridge.test.ts` now asserts against the source of
+`admin.tsx` that the key is present. Deleting the line fails the suite.
+
+## The media bridge
+
+`MediaPickerPort` is a render seam:
+
+```ts
+renderPicker(props: { onPick(item): void; onClose(): void }): ReactNode
+```
+
+The bridge returns the CMS's own `MediaPickerDialog` with `accept="image"`. Not
+a wrapper around it and not a reimplementation — the same component every other
+inspector uses, so browsing, searching, folders and **upload** all come along
+for free. The popup package never uploads anything and never learns which
+storage provider the site uses.
+
+What crosses the boundary is `{ src, name?, alt? }`: the stable public URL the
+library already serves to the site, the filename to show, and the library's own
+description when it has one. `toHostMediaItem` returns `null` for a row with no
+address rather than passing an empty string on.
+
+The URL must be the **public** one. A signed or expiring link renders in the
+builder and 404s a month later on the live site, which is why the popup package
+refuses those shapes itself in `checkMediaReference`.
+
+## The webhook layers
+
+Opt-in delivery is split across all three layers, and the split is the security
+model rather than a tidiness preference.
+
+| Layer | Has |
+| --- | --- |
+| lightweight-popup | The destinations screen and the delivery log. No fetch, no crypto, no database |
+| **this package** | `webhook-url-guard.ts`, `popup-optin-webhook-core.ts`, `popup-optin-trigger.ts` — validation, signing, the retry schedule, the genuine-opt-in predicate, field selection |
+| The site | Tables, server functions, `process.env` secret resolution, routing |
+
+Everything here is pure and host-agnostic: it is handed a row and a secret and
+returns an outcome. It never reads an environment variable and never opens a
+database connection, so the same code is testable without either.
+
+`src/server/*` is server-only by convention **and** by reachability: nothing in
+`src/backoffice` or `src/popups` imports it, which is what keeps delivery code
+out of every client bundle. The host's own chunk-boundary test proves that on
+the built assets.
+
+### The one rule that matters
+
+**Delivery is triggered from the stored submission, on the server.** The
+browser contributes a popup key and nothing else. There is no parameter that
+carries a payload, an endpoint or a recipient, so a crafted request cannot make
+the server send anything anywhere.
+
+`shouldDeliverOptIn` is the only predicate. A honeypot's
+`{ ok: true, skipped: true }` — the deliberate lie the form system tells a bot —
+is **not** an opt-in. Neither is a "yes" click, a preview, or a test-mode popup.
+
+### Secrets
+
+A destination stores the **name** of an environment variable, never a value.
+The host resolves it at delivery time. The admin port's `DestinationRecord`
+carries `secretConfigured: boolean` and an `endpointDisplay` with the query
+string removed; there is no field on it that could hold a credential, and the
+form that creates one has nowhere to type a secret.
+
+## Registering it on a site
+
+```ts
+import { registerPopupModule } from "@bygghammar/cms-platform/popups";
+```
+
+The host supplies its `fns` object. The webhook slots on it —
+`listWebhookDestinations`, `saveWebhookDestination`, `deleteWebhookDestination`,
+`sendTestWebhook`, `listWebhookDeliveries` — are **optional**. A site with no
+webhook tables simply omits them and the destinations screen is not offered;
+nothing breaks and no dead menu item appears.

package/migrations/20260902090000_dc072b25-8467-46ae-aef3-0ccdf40aa7eb.sql

@@ -0,0 +1,274 @@
+-- Editing locks for CMS resources ---------------------------------------
+--
+-- One row per resource somebody currently has open in an editor. The primary
+-- key is the resource itself, so two editors racing to open the same page
+-- contend on a single unique index and exactly one of them wins — the reason
+-- every mutation below happens inside one statement rather than a read
+-- followed by a write.
+--
+-- Locks expire. A browser that crashes, a laptop that sleeps or a tab closed
+-- without warning leaves a row behind, and `expires_at` makes that row
+-- harmless a couple of minutes later without anyone having to intervene.
+
+CREATE TABLE IF NOT EXISTS public.cms_edit_locks (
+  resource_type text        NOT NULL,
+  resource_id   text        NOT NULL,
+  user_id       uuid        NOT NULL,
+  user_email    text,
+  user_name     text,
+  session_id    text        NOT NULL,
+  acquired_at   timestamptz NOT NULL DEFAULT now(),
+  refreshed_at  timestamptz NOT NULL DEFAULT now(),
+  expires_at    timestamptz NOT NULL,
+  PRIMARY KEY (resource_type, resource_id)
+);
+
+CREATE INDEX IF NOT EXISTS cms_edit_locks_expires_at_idx
+  ON public.cms_edit_locks (expires_at);
+
+-- `session_id` is a bearer token: knowing it would let another browser pose as
+-- the holder on a save. Staff may inspect the operational fields, but only the
+-- definer functions below may read that column on their behalf.
+REVOKE ALL ON public.cms_edit_locks FROM PUBLIC, anon, authenticated;
+GRANT SELECT (
+  resource_type, resource_id, user_id, user_email, user_name,
+  acquired_at, refreshed_at, expires_at
+) ON public.cms_edit_locks TO authenticated;
+GRANT ALL ON public.cms_edit_locks TO service_role;
+ALTER TABLE public.cms_edit_locks ENABLE ROW LEVEL SECURITY;
+
+-- Staff may read who is editing what. Nobody writes this table directly:
+-- every change goes through the SECURITY DEFINER functions below, which is
+-- what makes "take the lock" atomic and keeps a client from inventing a lock
+-- in someone else's name.
+DROP POLICY IF EXISTS "Staff view edit locks" ON public.cms_edit_locks;
+CREATE POLICY "Staff view edit locks" ON public.cms_edit_locks
+  FOR SELECT TO authenticated USING (public.is_staff(app.current_user_id()));
+
+-- Shape one row for the client. An expired row reads as "not locked", so no
+-- caller has to know the expiry rule. The session id is never returned: it is
+-- the bearer value used to distinguish tabs, not display data.
+CREATE OR REPLACE FUNCTION public.cms_edit_lock_json(
+  _row        public.cms_edit_locks,
+  _viewer     uuid,
+  _session_id text
+)
+RETURNS jsonb
+LANGUAGE sql
+STABLE
+SET search_path = public, pg_temp
+AS $$
+  SELECT CASE
+    WHEN _row.resource_id IS NULL OR _row.expires_at <= now()
+      THEN jsonb_build_object('locked', false, 'held', false, 'now', now())
+    ELSE jsonb_build_object(
+      'locked',      true,
+      'held',        (_row.user_id = _viewer
+                       AND _session_id IS NOT NULL
+                       AND _row.session_id = _session_id),
+      'sameUser',    (_row.user_id = _viewer),
+      'resourceType', _row.resource_type,
+      'resourceId',   _row.resource_id,
+      'userId',       _row.user_id,
+      'userEmail',    _row.user_email,
+      'userName',     _row.user_name,
+      'acquiredAt',   _row.acquired_at,
+      'refreshedAt',  _row.refreshed_at,
+      'expiresAt',    _row.expires_at,
+      'now',          now()
+    )
+  END
+$$;
+
+-- Take a lock, or extend one we already hold — the same call, because that is
+-- also what a heartbeat needs: after a laptop wakes up the lock may have
+-- expired, and re-taking it is right precisely when nobody else claimed it.
+CREATE OR REPLACE FUNCTION public.cms_acquire_edit_lock(
+  _resource_type text,
+  _resource_id   text,
+  _session_id    text,
+  _ttl_seconds   integer DEFAULT 120,
+  _steal         boolean DEFAULT false
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid    uuid := app.current_user_id();
+  _email  text;
+  _name   text;
+  _type   text := btrim(_resource_type);
+  _id     text := btrim(_resource_id);
+  _sess   text := btrim(_session_id);
+  _ttl    interval;
+  _row    public.cms_edit_locks;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  IF _type IS NULL OR _type = '' OR _id IS NULL OR _id = ''
+     OR _sess IS NULL OR _sess = '' THEN
+    RAISE EXCEPTION 'A resource type, resource id and session id are all required'
+      USING ERRCODE = '22023';
+  END IF;
+  IF _steal AND NOT public.has_role(_uid, 'superadmin'::public.app_role) THEN
+    RAISE EXCEPTION 'Forbidden — superadmin only' USING ERRCODE = '42501';
+  END IF;
+
+  _ttl := make_interval(secs => LEAST(3600, GREATEST(15, COALESCE(_ttl_seconds, 120))));
+
+  -- The name shown to whoever is blocked comes from the server, never from
+  -- the caller, so a lock cannot be taken under someone else's name.
+  SELECT au.email, au.display_name INTO _email, _name
+    FROM public.app_users au WHERE au.id = _uid;
+
+  INSERT INTO public.cms_edit_locks AS l
+    (resource_type, resource_id, user_id, user_email, user_name, session_id, expires_at)
+  VALUES (_type, _id, _uid, _email, _name, _sess, now() + _ttl)
+  ON CONFLICT (resource_type, resource_id) DO UPDATE
+    SET user_id      = EXCLUDED.user_id,
+        user_email   = EXCLUDED.user_email,
+        user_name    = EXCLUDED.user_name,
+        session_id   = EXCLUDED.session_id,
+        acquired_at  = CASE
+                         WHEN l.user_id = EXCLUDED.user_id
+                          AND l.session_id = EXCLUDED.session_id
+                         THEN l.acquired_at ELSE now()
+                       END,
+        refreshed_at = now(),
+        expires_at   = EXCLUDED.expires_at
+    WHERE l.expires_at <= now()
+       OR (l.user_id = EXCLUDED.user_id AND l.session_id = EXCLUDED.session_id)
+       OR _steal
+  RETURNING l.* INTO _row;
+
+  -- The conflict clause declined: somebody else holds a live lock. Report who.
+  IF _row.resource_id IS NULL THEN
+    SELECT * INTO _row FROM public.cms_edit_locks
+      WHERE resource_type = _type AND resource_id = _id;
+  END IF;
+
+  -- Opportunistic sweep, so the table never needs a scheduled job.
+  DELETE FROM public.cms_edit_locks WHERE expires_at <= now() - interval '1 day';
+
+  RETURN public.cms_edit_lock_json(_row, _uid, _sess);
+END;
+$$;
+
+-- Who holds a resource right now. Read-only; an expired row reads as free.
+CREATE OR REPLACE FUNCTION public.cms_edit_lock_status(
+  _resource_type text,
+  _resource_id   text,
+  _session_id    text DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+STABLE
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid uuid := app.current_user_id();
+  _row public.cms_edit_locks;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  SELECT * INTO _row FROM public.cms_edit_locks
+    WHERE resource_type = btrim(_resource_type) AND resource_id = btrim(_resource_id);
+  RETURN public.cms_edit_lock_json(_row, _uid, NULLIF(btrim(_session_id), ''));
+END;
+$$;
+
+-- Give a lock back. Only ever our own, and only the session that took it.
+CREATE OR REPLACE FUNCTION public.cms_release_edit_lock(
+  _resource_type text,
+  _resource_id   text,
+  _session_id    text
+)
+RETURNS boolean
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid  uuid := app.current_user_id();
+  _gone integer;
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  DELETE FROM public.cms_edit_locks
+    WHERE resource_type = btrim(_resource_type)
+      AND resource_id   = btrim(_resource_id)
+      AND user_id       = _uid
+      AND session_id    = btrim(_session_id);
+  GET DIAGNOSTICS _gone = ROW_COUNT;
+  RETURN _gone > 0;
+END;
+$$;
+
+-- Every live lock, for an administrator looking at a stuck editor. Recreate
+-- the function so an earlier local run of this unreleased migration also gets
+-- the redacted return shape.
+DROP FUNCTION IF EXISTS public.cms_list_edit_locks();
+CREATE FUNCTION public.cms_list_edit_locks()
+RETURNS TABLE (
+  resource_type text,
+  resource_id   text,
+  user_id       uuid,
+  user_email    text,
+  user_name     text,
+  acquired_at   timestamptz,
+  refreshed_at  timestamptz,
+  expires_at    timestamptz
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+STABLE
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  _uid uuid := app.current_user_id();
+BEGIN
+  IF _uid IS NULL OR NOT public.is_staff(_uid) THEN
+    RAISE EXCEPTION 'Forbidden' USING ERRCODE = '42501';
+  END IF;
+  RETURN QUERY
+    SELECT
+      l.resource_type,
+      l.resource_id,
+      l.user_id,
+      l.user_email,
+      l.user_name,
+      l.acquired_at,
+      l.refreshed_at,
+      l.expires_at
+    FROM public.cms_edit_locks l
+    WHERE l.expires_at > now()
+    ORDER BY l.refreshed_at DESC;
+END;
+$$;
+
+-- Nothing here is for the anonymous role, and a definer function that decides
+-- who may edit is not something to leave on PUBLIC's default grant. The bodies
+-- check `is_staff` regardless; this is the second lock on the same door.
+REVOKE ALL ON FUNCTION public.cms_edit_lock_json(public.cms_edit_locks, uuid, text)
+  FROM PUBLIC, anon, authenticated, service_role;
+REVOKE ALL ON FUNCTION public.cms_acquire_edit_lock(text, text, text, integer, boolean) FROM PUBLIC, anon;
+REVOKE ALL ON FUNCTION public.cms_edit_lock_status(text, text, text) FROM PUBLIC, anon;
+REVOKE ALL ON FUNCTION public.cms_release_edit_lock(text, text, text) FROM PUBLIC, anon;
+REVOKE ALL ON FUNCTION public.cms_list_edit_locks() FROM PUBLIC, anon;
+
+-- `cms_edit_lock_json` is an implementation helper called by the definer
+-- functions; clients do not need an RPC surface for arbitrary composite rows.
+GRANT EXECUTE ON FUNCTION public.cms_acquire_edit_lock(text, text, text, integer, boolean)
+  TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.cms_edit_lock_status(text, text, text)
+  TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.cms_release_edit_lock(text, text, text)
+  TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.cms_list_edit_locks()
+  TO authenticated, service_role;