@bygghammar/cms-platform 0.90.0-m7.5 → 0.90.0-m7.9

package/CHANGELOG.md

@@ -8,6 +8,107 @@ matches `package.json` exactly. See
 Versions 0.1.0 through 0.78.0 predate this repository and were reconstructed
 from the published npm tarballs.
 
+## 0.90.0-m7.9
+
+- The email settings screen says where provider credentials actually go. An
+  administrator told only that "passwords are stored as server secrets" does the
+  one thing the sentence was meant to prevent and pastes the password into the
+  CMS field in front of them, so the screen names the configuration file, the
+  environment-variable names and the secret-name convention for that
+  installation instead. It stays value-free: no secret is read, returned or
+  rendered, and hosts supply their own deployment root through
+  `secretsLocation` — including `/`, which stays absolute.
+- Optional block content whose localized value is empty is no longer rendered.
+  A heading or paragraph written in one locale and left blank in another used to
+  leave its empty markup behind in the locale that had nothing to say.
+- Nested navigation items are editable. Only top-level entries could be changed,
+  so fixing a typo in a child link meant deleting it and building it again.
+- Rich text holds up at length, and a block chooses how it appears. Each block
+  carries its own reveal mode; `Reveal` still defaults to `fade`, so every
+  already-published page looks exactly as it did.
+- Cooperative editing locks stop two administrators overwriting each other. A
+  lock is taken when an editor opens a resource, renewed while it stays open and
+  released when it closes, and a second editor is told who holds it instead of
+  silently losing the earlier write. Pages, global sections, shared content,
+  navigation, contact details, forms, form defaults, form history and page SEO
+  are covered, and the refusal is enforced in the server cores — not only by
+  disabling controls in the interface.
+- The lock's session token is private and the session match is exact.
+  `session_id` is never returned by any read: authenticated callers hold column
+  grants that omit it, the JSON shape drops it, and the administrator listing
+  returns a redacted row. A write against a live lock succeeds only for the
+  exact, non-empty session that holds it. Empty or malformed lock responses fail
+  closed rather than reading as "free", a stale asynchronous reply cannot revive
+  a lock that was already released, reopening an editor can no longer let its
+  own release overtake its next acquire, and a duplicated browser tab is given
+  its own session identity — Web Locks where the browser provides them, a
+  best-effort BroadcastChannel fallback where it does not.
+- Lock storage is a host port, not a provider. `editLockActionCore` and
+  `assertEditable` reach the database only through `EditLockAdapter`
+  (`@bygghammar/cms-platform/server/edit-lock-adapter`) — five methods covering
+  acquire, status, release, list and the staff check — so an application on
+  ordinary PostgreSQL implements it with the SQL it already writes, with no
+  PostgREST client and no `supabase` object to imitate. Hosts that already build
+  `{ supabase: { rpc }, userId, claims }` for their other cores keep passing
+  exactly that: `createSupabaseEditLockAdapter` is applied for them
+  automatically and nothing on an existing host changes.
+- Locks require a migration and host wiring, and change nothing until both are
+  done. `migrations/20260902090000_dc072b25-8467-46ae-aef3-0ccdf40aa7eb.sql`
+  creates the table and its functions; `docs/EDIT-LOCKS.md` is the host
+  contract: one authenticated server endpoint through `editLockActionCore`, one
+  `EditLockProvider` built with `createEditLockApi`, the non-empty
+  `editSessionId` forwarded to every protected write, `pageKey` passed to
+  `PageSeoPanelView`, and the `edit_locked:` message prefix preserved across the
+  host's own transport. Until then every screen behaves exactly as it did before
+  locks existed.
+- The lock is a cooperative server preflight, not a transaction-atomic write
+  fence. The check and the mutation are separate statements, so a host needing
+  strict exclusion must put both in one transaction or RPC. Full-document exits
+  deliberately let the lock lapse by TTL — 120 seconds by default — rather than
+  race a reload against its own release.
+- Verified on PostgreSQL 16 and 17: the migration applies in a single
+  transaction against a throwaway container carrying a host's real role,
+  authentication and user objects; the grants, the RLS policy and the
+  `SECURITY DEFINER` `search_path` come out as written; twenty simultaneous
+  acquires of one resource leave exactly one holder and no errors; and a
+  shadowing `pg_temp` object cannot reach inside a definer body.
+- Not verified in this release: the migration has not been applied to any real
+  staging or production database, and the two-user real-browser lock behaviour
+  has not been exercised against a live host. Both remain required before
+  production use.
+
+## 0.90.0-m7.8
+
+- Requires `@bygghammar/lightweight-popup@>=0.2.0-m7.8`. `m7.6` and `m7.7` were
+  tagged and never published: two defects in the release workflow stopped them
+  after every gate had passed. The form-identity work they were meant to carry
+  is unchanged and ships here.
+- The release workflow gets both corrections, proven in lightweight-popup:
+  the redundant post-checkout `git fetch` is gone (checkout already brings
+  every branch, and its credentials are removed on the way out), and
+  `npm pack`'s destination is created before it is packed into, with the same
+  directory carried to the tarball verification rather than spelled twice.
+- `ops/verify-release-tag.mjs` checks `refs/remotes/origin/main` is present
+  before asking `merge-base` about it, so a checkout that fetched too little no
+  longer reports itself as a tag on an unmerged branch.
+
+## 0.90.0-m7.6
+
+- A form submitted from inside a popup now says so. `FormRenderer` and
+  `ManagedForm` take an opaque `context` that is merged into the submission,
+  and the popup module fills it with `{ popupKey }` — the form system keeps
+  knowing nothing about the features that use it. Without this the request was
+  indistinguishable from the same form filled on an ordinary page, so the
+  server stored an ordinary entry and every delivery configured on the popup
+  silently did nothing.
+- `HostSubmitFormInput` gains `popupKey?: string`, the only popup-shaped value
+  the browser sends. Destination, endpoint, signing secret and which fields may
+  leave are all read on the server from the popup's stored configuration.
+- Drafts and the builder preview carry no context, so a part-filled form and an
+  editor checking a layout cannot fire a campaign's webhook.
+- Requires `@bygghammar/lightweight-popup@>=0.2.0-m7.6`, which is where the
+  identity comes from.
+
 ## 0.90.0-m7.5
 
 - `BackofficeHost.pages.fns.listPages` is declared. It was what

package/README.md

@@ -25,6 +25,14 @@ apply the canonical schema with `bunx cms-platform-migrations`, import
 `theme.css`, register host components / platform data / translations, wrap the
 server cores and mount the shared backoffice views.
 
+## Editing locks
+
+`docs/EDIT-LOCKS.md` is what a host wires so two administrators cannot
+overwrite each other: run the migration, expose one server endpoint through
+`editLockActionCore`, mount `EditLockProvider` with `createEditLockApi`, and
+forward `editSessionId` to the saves. Until that is done every screen behaves
+exactly as it did before locks existed.
+
 ## Compatibility policy
 
 - `CHANGELOG.md` records every release; read it before upgrading.
@@ -119,8 +127,14 @@ bun run check   # typecheck + tests + package verification
 
 The package ships TypeScript sources; there is no build output. Every change
 goes through a pull request, and every release is triggered by pushing a
-`vX.Y.Z` tag that matches `package.json`, which publishes to npm from GitHub
-Actions using the repository secret `NPM_TOKEN`. Never publish manually.
+`vX.Y.Z` tag that matches `package.json`. That tag runs
+`.github/workflows/publish.yml`, which publishes to npm using **Trusted
+Publishing**: GitHub mints a short-lived OIDC token scoped to that single
+workflow run, and npm exchanges it for publish rights through the package's
+Trusted Publisher configuration. No long-lived npm credential takes part — no
+`NPM_TOKEN`, no `NODE_AUTH_TOKEN`, no OTP. [RELEASING.md](./RELEASING.md) is
+what the workflow checks and the npm settings it has to match. Never publish
+manually.
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow and changelog
 conventions. Consumers install an explicit released version such as

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/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;