@bygghammar/cms-platform 0.30.1 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.31.0
+
+- Added `backoffice/SharedContentListView` — the shared-content library screen
+  with host-supplied section registry, override chips and preview thumbnails.
+- Added `backoffice/seo/SeoListView` — the SEO index (`SeoListView`) and page
+  shell (`SeoDetailView`) around the host's page SEO panel.
+
 ## 0.30.0
 
 - Added `backoffice/PagesListView` — the page-builder index with public URLs per

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": false,
@@ -135,7 +135,13 @@
     "./backoffice/GlobalSectionBuilderView": "./src/backoffice/GlobalSectionBuilderView.tsx",
     "./backoffice/ReviewsView": "./src/backoffice/ReviewsView.tsx",
     "./backoffice/PagesListView": "./src/backoffice/PagesListView.tsx",
-    "./backoffice/BlocksLibraryView": "./src/backoffice/BlocksLibraryView.tsx"
+    "./backoffice/BlocksLibraryView": "./src/backoffice/BlocksLibraryView.tsx",
+    "./backoffice/SharedContentListView": "./src/backoffice/SharedContentListView.tsx",
+    "./backoffice/seo/SeoListView": "./src/backoffice/seo/SeoListView.tsx",
+    "./server/audit-core": "./src/server/audit-core.ts",
+    "./server/review-image-validate": "./src/server/review-image-validate.ts",
+    "./server/media-library-core": "./src/server/media-library-core.ts",
+    "./server/admin-core": "./src/server/admin-core.ts"
   },
   "dependencies": {
     "fflate": "^0.8.3"

package/src/backoffice/SharedContentListView.tsx

@@ -0,0 +1,103 @@
+/**
+ * Host-agnostic "Shared content" library screen.
+ *
+ * Lists the site-wide content records (one per section key). The host supplies
+ * the section registry, override state, thumbnails and navigation, so every
+ * site gets the same screen without the package knowing its content model.
+ */
+import { useState, type ReactNode } from "react";
+import { Check, ChevronRight, Eye } from "lucide-react";
+
+import { PreviewLightbox } from "./PreviewLightbox";
+
+export type SharedContentSection = {
+  key: string;
+  label: string;
+  description?: string;
+};
+
+export type SharedContentListDeps = {
+  sections: readonly SharedContentSection[];
+  /** True when this key has a database override (shows the "edited" chip). */
+  hasOverride: (key: string) => boolean;
+  /** Navigate to the editor for one section key. */
+  openEditor: (key: string) => void;
+  /** Preview URL for one section key, e.g. `/preview/section/${key}`. */
+  previewSrc: (key: string) => string;
+  /** Thumbnail for one section key; host-rendered so it can read its own data. */
+  renderThumb: (key: string) => ReactNode;
+};
+
+export function SharedContentListView({ deps }: { deps: SharedContentListDeps }): ReactNode {
+  const { sections, hasOverride, openEditor, previewSrc, renderThumb } = deps;
+  const [preview, setPreview] = useState<{ key: string; label: string } | null>(null);
+
+  return (
+    <div className="p-8 md:p-12 w-full">
+      <div className="text-[0.7rem] uppercase tracking-[0.22em] text-ink/55">Shared content</div>
+      <h1 className="mt-2 font-serif text-3xl md:text-4xl text-ink">Shared content</h1>
+      <p className="mt-4 text-ink/65 max-w-2xl">
+        Site-wide content records — one per key. Any page using the matching block reads this
+        content, so editing here updates every page at once. For global blocks (reusable groups of
+        blocks) with their own layout, use Global blocks instead. Thumbnails refresh when you save.
+      </p>
+
+      <ul className="mt-10 divide-y divide-ink/10 border-y border-ink/10">
+        {sections.map((section) => (
+          <li key={section.key}>
+            <button
+              type="button"
+              onClick={() => openEditor(section.key)}
+              className="flex w-full items-center gap-4 py-5 hover:bg-white transition-colors px-4 -mx-4 text-left"
+            >
+              <span
+                role="button"
+                tabIndex={0}
+                title="Preview section"
+                onClick={(e) => {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  setPreview({ key: section.key, label: section.label });
+                }}
+                onKeyDown={(e) => {
+                  if (e.key !== "Enter" && e.key !== " ") return;
+                  e.preventDefault();
+                  e.stopPropagation();
+                  setPreview({ key: section.key, label: section.label });
+                }}
+                className="group relative shrink-0"
+              >
+                {renderThumb(section.key)}
+                <span className="absolute inset-0 hidden items-center justify-center bg-ink/50 text-white group-hover:flex">
+                  <Eye className="size-4" />
+                </span>
+              </span>
+              <span className="flex-1 min-w-0">
+                <span className="flex items-center gap-3">
+                  <span className="font-serif text-lg text-ink">{section.label}</span>
+                  {hasOverride(section.key) && (
+                    <span className="inline-flex items-center gap-1 text-[0.65rem] uppercase tracking-[0.18em] text-sea">
+                      <Check className="size-3" />
+                      edited
+                    </span>
+                  )}
+                </span>
+                {section.description && (
+                  <span className="mt-1 block text-sm text-ink/60">{section.description}</span>
+                )}
+              </span>
+              <ChevronRight className="size-5 text-ink/40" />
+            </button>
+          </li>
+        ))}
+      </ul>
+
+      <PreviewLightbox
+        open={preview != null}
+        onClose={() => setPreview(null)}
+        src={preview ? previewSrc(preview.key) : ""}
+        title={preview?.label ?? ""}
+      />
+    </div>
+  );
+}

package/src/backoffice/seo/SeoListView.tsx

@@ -0,0 +1,104 @@
+/**
+ * Host-agnostic SEO index and page shell.
+ *
+ * The host resolves titles, slugs and override state from its own page registry
+ * plus CMS overrides; these components own only presentation and navigation.
+ */
+import type { ReactNode } from "react";
+import { Check, ChevronLeft, ChevronRight } from "lucide-react";
+
+export type SeoListRow = {
+  /** Page key, e.g. `index` or a CMS-only page key. */
+  key: string;
+  /** Title shown in the default locale. */
+  title: string;
+  /** Public path in the default locale, e.g. `/` or `/kontakt`. */
+  path: string;
+  hasOverride: boolean;
+};
+
+export type SeoListDeps = {
+  rows: readonly SeoListRow[];
+  /** Navigate to the SEO editor for one page key. */
+  openEditor: (key: string) => void;
+};
+
+export function SeoListView({ deps }: { deps: SeoListDeps }): ReactNode {
+  const { rows, openEditor } = deps;
+
+  return (
+    <div className="p-8 md:p-12 w-full">
+      <div className="text-[0.7rem] uppercase tracking-[0.22em] text-ink/55">SEO</div>
+      <h1 className="mt-2 font-serif text-3xl md:text-4xl text-ink">SEO &amp; slugs</h1>
+
+      <p className="mt-4 text-ink/65 max-w-xl">
+        Edit title, description, social previews and URL slug per language. Changes override the
+        defaults from the codebase and are used directly by canonical, hreflang and sitemap.
+      </p>
+
+      <ul className="mt-10 divide-y divide-ink/10 border-y border-ink/10">
+        {rows.map((row) => (
+          <li key={row.key}>
+            <button
+              type="button"
+              onClick={() => openEditor(row.key)}
+              className="flex w-full items-center gap-4 py-5 hover:bg-white transition-colors px-4 -mx-4 text-left"
+            >
+              <span className="flex-1 min-w-0">
+                <span className="flex items-center gap-3">
+                  <span className="font-serif text-lg text-ink">{row.title}</span>
+                  {row.hasOverride && (
+                    <span className="inline-flex items-center gap-1 text-[0.65rem] uppercase tracking-[0.18em] text-sea">
+                      <Check className="size-3" />
+                      edited
+                    </span>
+                  )}
+                </span>
+                <span className="mt-1 block text-sm text-ink/60">
+                  <span className="font-mono">{row.key}</span> · {row.path}
+                </span>
+              </span>
+              <ChevronRight className="size-5 text-ink/40" />
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+export type SeoDetailDeps = {
+  pageKey: string;
+  /** Navigate back to the SEO index. */
+  onBack: () => void;
+  /** The host's page SEO panel for this page key. */
+  children: ReactNode;
+};
+
+export function SeoDetailView({ deps }: { deps: SeoDetailDeps }): ReactNode {
+  const { pageKey, onBack, children } = deps;
+
+  return (
+    <div className="p-8 md:p-12 w-full">
+      <button
+        type="button"
+        onClick={onBack}
+        className="inline-flex items-center gap-2 text-xs uppercase tracking-[0.22em] text-ink/60 hover:text-ink"
+      >
+        <ChevronLeft className="size-4" />
+        All SEO pages
+      </button>
+
+      <div className="mt-6 text-[0.7rem] uppercase tracking-[0.22em] text-ink/55">
+        Page · {pageKey}
+      </div>
+      <h1 className="mt-2 font-serif text-3xl md:text-4xl text-ink">Page SEO</h1>
+      <p className="mt-3 text-ink/65 max-w-xl">
+        Defaults come from the codebase. Changes are saved per language and used by canonical,
+        hreflang, Open Graph and Twitter cards.
+      </p>
+
+      <div className="mt-8">{children}</div>
+    </div>
+  );
+}

package/src/server/admin-core.ts

@@ -0,0 +1,383 @@
+/**
+ * Host-agnostic administration server logic: users, roles, log browsing, email
+ * settings and email providers.
+ *
+ * Authorization always runs through the host's own `is_staff` / `has_role`
+ * database functions against the authenticated client, so row-level security
+ * applies as the signed-in user. Privileged operations (creating auth users,
+ * writing roles, storing provider config) take the privileged client the host
+ * supplies, and only after the role check above has passed.
+ *
+ * Every mutation writes an audit entry. Sending mail is injected by the host so
+ * this module stays free of transport code.
+ */
+import type { SupabaseClient } from "@supabase/supabase-js";
+
+import { writeAudit } from "./audit-core";
+import { actorEmail, assertRole, assertStaff, type PlatformAuthContext } from "./guards";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export const ALL_PLATFORM_ROLES = ["superadmin", "admin", "editor", "seo", "user"] as const;
+export type PlatformRole = (typeof ALL_PLATFORM_ROLES)[number];
+
+export const PROVIDER_KINDS = ["smtp", "ses", "lovable", "mailgun", "http"] as const;
+export type ProviderKind = (typeof PROVIDER_KINDS)[number];
+
+export type AdminDeps = {
+  context: PlatformAuthContext & { supabase: SupabaseClient };
+  admin: () => Promise<SupabaseClient>;
+};
+
+export type AdminUser = {
+  id: string;
+  email: string;
+  created_at: string;
+  last_sign_in_at: string | null;
+  email_confirmed_at: string | null;
+  roles: PlatformRole[];
+};
+
+const anyClient = (client: SupabaseClient) => client as unknown as any;
+
+async function audit(
+  deps: AdminDeps,
+  action: string,
+  entity: string,
+  entityId?: string,
+  meta: Record<string, unknown> = {},
+) {
+  const admin = await deps.admin();
+  await writeAudit(admin as never, deps.context, {
+    action,
+    entity,
+    entityId: entityId ?? null,
+    meta,
+  });
+}
+
+/* ============================= USERS ============================= */
+
+/** Accounts with their roles. Staff may read; only superadmins may mutate. */
+export async function listUsersCore(deps: AdminDeps): Promise<AdminUser[]> {
+  await assertStaff(deps.context);
+  const admin = await deps.admin();
+  const { data, error } = await admin.auth.admin.listUsers({ page: 1, perPage: 200 });
+  if (error) throw new Error(error.message);
+
+  const ids = data.users.map((u) => u.id);
+  const { data: roleRows } = await anyClient(admin)
+    .from("user_roles")
+    .select("user_id, role")
+    .in("user_id", ids.length ? ids : ["00000000-0000-0000-0000-000000000000"]);
+
+  const rolesByUser = new Map<string, PlatformRole[]>();
+  for (const r of ((roleRows ?? []) as any[]) ?? []) {
+    const arr = rolesByUser.get(r.user_id) ?? [];
+    arr.push(r.role as PlatformRole);
+    rolesByUser.set(r.user_id, arr);
+  }
+
+  return data.users.map((u) => ({
+    id: u.id,
+    email: u.email ?? "",
+    created_at: u.created_at,
+    last_sign_in_at: u.last_sign_in_at ?? null,
+    email_confirmed_at: u.email_confirmed_at ?? null,
+    roles: rolesByUser.get(u.id) ?? [],
+  }));
+}
+
+export async function createUserCore(
+  deps: AdminDeps,
+  input: { email: string; password?: string; roles?: PlatformRole[] },
+): Promise<{ id: string }> {
+  await assertRole(deps.context, "superadmin");
+  const admin = await deps.admin();
+  const roles = input.roles ?? [];
+  const { data: created, error } = await admin.auth.admin.createUser({
+    email: input.email,
+    ...(input.password ? { password: input.password } : {}),
+    email_confirm: true,
+  });
+  if (error) throw new Error(error.message);
+  const uid = created.user!.id;
+  if (roles.length) {
+    await anyClient(admin)
+      .from("user_roles")
+      .insert(roles.map((role) => ({ user_id: uid, role })));
+  }
+  await audit(deps, "user.create", "auth.users", uid, { email: input.email, roles });
+  return { id: uid };
+}
+
+export async function deleteUserCore(
+  deps: AdminDeps,
+  input: { userId: string },
+): Promise<{ ok: true }> {
+  await assertRole(deps.context, "superadmin");
+  if (input.userId === deps.context.userId) throw new Error("Cannot delete yourself");
+  const admin = await deps.admin();
+  const { error } = await admin.auth.admin.deleteUser(input.userId);
+  if (error) throw new Error(error.message);
+  await audit(deps, "user.delete", "auth.users", input.userId);
+  return { ok: true };
+}
+
+export async function setUserPasswordCore(
+  deps: AdminDeps,
+  input: { userId: string; password: string },
+): Promise<{ ok: true }> {
+  await assertRole(deps.context, "superadmin");
+  const admin = await deps.admin();
+  const { error } = await admin.auth.admin.updateUserById(input.userId, {
+    password: input.password,
+  });
+  if (error) throw new Error(error.message);
+  await audit(deps, "user.password_reset", "auth.users", input.userId);
+  return { ok: true };
+}
+
+export async function sendPasswordResetEmailCore(
+  deps: AdminDeps,
+  input: { email: string },
+): Promise<{ ok: true }> {
+  await assertRole(deps.context, "superadmin");
+  const admin = await deps.admin();
+  const { error } = await admin.auth.admin.generateLink({
+    type: "recovery",
+    email: input.email,
+  });
+  if (error) throw new Error(error.message);
+  await audit(deps, "user.send_reset", "auth.users", undefined, { email: input.email });
+  return { ok: true };
+}
+
+/* ============================= ROLES ============================= */
+
+/** Replace a user's role set. A superadmin can never strip their own access. */
+export async function setUserRolesCore(
+  deps: AdminDeps,
+  input: { userId: string; roles: PlatformRole[] },
+): Promise<{ ok: true }> {
+  await assertRole(deps.context, "superadmin");
+  if (input.userId === deps.context.userId && !input.roles.includes("superadmin")) {
+    throw new Error("Cannot remove your own superadmin role");
+  }
+  const admin = await deps.admin();
+  await anyClient(admin).from("user_roles").delete().eq("user_id", input.userId);
+  if (input.roles.length) {
+    const rows = Array.from(new Set(input.roles)).map((role) => ({
+      user_id: input.userId,
+      role,
+    }));
+    const { error } = await anyClient(admin).from("user_roles").insert(rows);
+    if (error) throw new Error(error.message);
+  }
+  await audit(deps, "user.set_roles", "user_roles", input.userId, { roles: input.roles });
+  return { ok: true };
+}
+
+/** Roles of the signed-in viewer; read as the user, so no privileged client. */
+export async function getMyRolesCore(deps: AdminDeps): Promise<PlatformRole[]> {
+  const { data, error } = await anyClient(deps.context.supabase)
+    .from("user_roles")
+    .select("role")
+    .eq("user_id", deps.context.userId);
+  if (error) throw new Error(error.message);
+  return ((data ?? []) as any[]).map((r) => r.role as PlatformRole);
+}
+
+/* ========================= LOG BROWSING ========================= */
+
+async function listLog(deps: AdminDeps, table: string, limit: number) {
+  await assertStaff(deps.context);
+  const { data, error } = await anyClient(deps.context.supabase)
+    .from(table)
+    .select("*")
+    .order("created_at", { ascending: false })
+    .limit(limit);
+  if (error) throw new Error(error.message);
+  return (data ?? []) as Record<string, unknown>[];
+}
+
+export function listAuditLogsCore(deps: AdminDeps, input?: { limit?: number }) {
+  return listLog(deps, "audit_logs", input?.limit ?? 200);
+}
+
+export function listEmailLogsCore(deps: AdminDeps, input?: { limit?: number }) {
+  return listLog(deps, "email_logs", input?.limit ?? 200);
+}
+
+/* ======================== EMAIL SETTINGS ======================== */
+
+export async function getEmailSettingsCore(deps: AdminDeps) {
+  await assertStaff(deps.context);
+  const { data, error } = await anyClient(deps.context.supabase)
+    .from("email_settings")
+    .select("*")
+    .eq("id", true)
+    .maybeSingle();
+  if (error) throw new Error(error.message);
+  return data as Record<string, unknown> | null;
+}
+
+export async function saveEmailSettingsCore(
+  deps: AdminDeps,
+  input: Record<string, unknown>,
+): Promise<{ ok: true }> {
+  await assertRole(deps.context, "superadmin");
+  const admin = await deps.admin();
+  const { error } = await anyClient(admin)
+    .from("email_settings")
+    .upsert({ id: true, ...input, updated_by: deps.context.userId }, { onConflict: "id" });
+  if (error) throw new Error(error.message);
+  await audit(deps, "email_settings.update", "email_settings", "singleton");
+  return { ok: true };
+}
+
+/* ======================= EMAIL PROVIDERS ======================= */
+
+export async function listEmailProvidersCore(deps: AdminDeps) {
+  await assertStaff(deps.context);
+  const { data, error } = await anyClient(deps.context.supabase)
+    .from("email_providers")
+    .select("*")
+    .order("sort_order", { ascending: true })
+    .order("created_at", { ascending: true });
+  if (error) throw new Error(error.message);
+  return (data ?? []) as Record<string, unknown>[];
+}
+
+export async function upsertEmailProviderCore(
+  deps: AdminDeps,
+  input: Record<string, unknown> & { id?: string; name: string; kind: ProviderKind },
+) {
+  await assertRole(deps.context, "superadmin");
+  const admin = await deps.admin();
+  const row = { ...input, updated_by: deps.context.userId };
+  const table = anyClient(admin).from("email_providers");
+  const query = input.id
+    ? table.update(row).eq("id", input.id).select("*").single()
+    : table.insert(row).select("*").single();
+  const { data: saved, error } = await query;
+  if (error) throw new Error(error.message);
+  await audit(
+    deps,
+    input.id ? "email_provider.update" : "email_provider.create",
+    "email_providers",
+    (saved as any).id,
+    { name: input.name, kind: input.kind },
+  );
+  return saved as Record<string, unknown>;
+}
+
+export async function deleteEmailProviderCore(
+  deps: AdminDeps,
+  input: { id: string },
+): Promise<{ ok: true }> {
+  await assertRole(deps.context, "superadmin");
+  const admin = await deps.admin();
+  const { error } = await anyClient(admin).from("email_providers").delete().eq("id", input.id);
+  if (error) throw new Error(error.message);
+  await audit(deps, "email_provider.delete", "email_providers", input.id);
+  return { ok: true };
+}
+
+/** Transport the host injects, so this module carries no SMTP/API client. */
+export type ProviderSender = (
+  provider: {
+    id: string;
+    name: string;
+    kind: string;
+    from_name: string | null;
+    from_email: string;
+    reply_to: string | null;
+    config: Record<string, unknown>;
+    secret_ref_name: string | null;
+  },
+  message: {
+    to: string;
+    subject: string;
+    html: string;
+    text: string;
+    fromName: string | null;
+    fromEmail: string;
+    replyTo: string | null;
+  },
+) => Promise<{ ok: true } | { ok: false; error: string }>;
+
+/**
+ * Send a probe message through one provider and log the outcome either way, so
+ * a misconfigured provider is visible in the email log rather than silent.
+ */
+export async function sendTestEmailCore(
+  deps: AdminDeps,
+  input: { provider_id: string; to: string },
+  send: ProviderSender,
+): Promise<{ ok: true }> {
+  await assertRole(deps.context, "superadmin");
+  const admin = await deps.admin();
+
+  const { data: provider, error: pErr } = await anyClient(admin)
+    .from("email_providers")
+    .select("*")
+    .eq("id", input.provider_id)
+    .single();
+  if (pErr || !provider) throw new Error(pErr?.message ?? "Provider not found");
+
+  const { data: settings } = await anyClient(admin)
+    .from("email_settings")
+    .select("*")
+    .eq("id", true)
+    .maybeSingle();
+
+  const fromEmail = provider.from_email ?? settings?.primary_from_email ?? null;
+  const fromName = provider.from_name ?? settings?.primary_from_name ?? null;
+  const replyTo = provider.reply_to ?? settings?.reply_to ?? null;
+  const subject = `Test email from ${provider.name}`;
+  const text = `This is a test email sent from the backoffice through the provider "${provider.name}" (${provider.kind}).`;
+  const html = `<p>${text}</p><p style="color:#666;font-size:12px">Sent ${new Date().toISOString()}</p>`;
+
+  const result = fromEmail
+    ? await send(
+        {
+          id: provider.id,
+          name: provider.name,
+          kind: provider.kind,
+          from_name: fromName,
+          from_email: fromEmail,
+          reply_to: replyTo,
+          config: (provider.config ?? {}) as Record<string, unknown>,
+          secret_ref_name: provider.secret_ref_name ?? null,
+        },
+        { to: input.to, subject, html, text, fromName, fromEmail, replyTo },
+      )
+    : ({ ok: false, error: "No from address configured for this provider or in the email settings." } as const);
+
+  await anyClient(admin)
+    .from("email_logs")
+    .insert({
+      to_address: input.to,
+      from_address: fromEmail,
+      reply_to: replyTo,
+      subject,
+      body_preview: text.slice(0, 200),
+      provider: provider.name,
+      status: result.ok ? "sent" : "failed",
+      error: result.ok ? null : result.error,
+      meta: { kind: provider.kind, provider_id: provider.id, test: true },
+    });
+
+  await audit(deps, "email_provider.test_send", "email_providers", provider.id, {
+    to: input.to,
+    ok: result.ok,
+    error: result.ok ? null : result.error,
+  });
+
+  if (!result.ok) throw new Error(result.error);
+  return { ok: true };
+}
+
+/** Actor email helper re-exported so hosts don't need the guards module too. */
+export { actorEmail };

package/src/server/audit-core.ts

@@ -0,0 +1,54 @@
+/**
+ * Host-agnostic audit trail writer.
+ *
+ * Every platform core records what an editor did in the append-only
+ * `audit_logs` table. The host passes a privileged client because the trail must
+ * be written even when the acting user cannot read it back, and the entry always
+ * carries the acting user's id and email so the log stays attributable.
+ *
+ * Auditing is deliberately best-effort: a failed log entry never fails the
+ * operation the editor asked for.
+ */
+import type { PlatformAuthContext } from "./guards";
+import { actorEmail } from "./guards";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** Minimal privileged-client shape the audit writer needs. */
+export type AuditClient = {
+  from: (table: string) => { insert: (row: any) => PromiseLike<{ error: any }> };
+};
+
+export type AuditEntry = {
+  action: string;
+  entity?: string | null;
+  entityId?: string | null;
+  meta?: Record<string, unknown>;
+};
+
+/** Write one audit entry. Never throws — logging must not break the action. */
+export async function writeAudit(
+  admin: AuditClient,
+  context: PlatformAuthContext,
+  entry: AuditEntry,
+): Promise<void> {
+  try {
+    const { error } = await admin.from("audit_logs").insert({
+      actor_id: context.userId,
+      actor_email: actorEmail(context),
+      action: entry.action,
+      entity: entry.entity ?? null,
+      entity_id: entry.entityId ?? null,
+      meta: (entry.meta ?? {}) as unknown,
+    });
+    if (error) console.warn("audit failed", error.message);
+  } catch (err) {
+    console.warn("audit failed", err);
+  }
+}
+
+/** Curried writer for a single entity kind, e.g. `media` or `page`. */
+export function auditWriter(admin: AuditClient, context: PlatformAuthContext, entity: string) {
+  return (action: string, entityId: string, meta: Record<string, unknown> = {}) =>
+    writeAudit(admin, context, { action, entity, entityId, meta });
+}

package/src/server/media-library-core.ts

@@ -0,0 +1,453 @@
+/**
+ * Host-agnostic media library server logic.
+ *
+ * Owns listing, soft delete into a recoverable bin, restore, purge, uploads and
+ * the bulk-overwrite helpers. The host supplies two clients — the authenticated
+ * one for reads (so row-level security applies as the signed-in user) and a
+ * privileged one for the storage moves and bin bookkeeping — and nothing else.
+ *
+ * Nothing here hard-deletes an asset except the explicit purge paths, which the
+ * host must gate on a superadmin check before calling.
+ */
+import type { SupabaseClient } from "@supabase/supabase-js";
+
+import { getMediaStorage } from "../media/storage";
+import { isSecondaryVariant, variantSiblings } from "../media/srcset";
+import { uniqueFileName } from "../media/filename";
+import { auditWriter } from "./audit-core";
+import type { PlatformAuthContext } from "./guards";
+import {
+  REVIEW_WIDTHS,
+  sanitizeReviewSlug,
+  validateReviewVariant,
+} from "./review-image-validate";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** What every core call needs from the host. */
+export type MediaLibraryDeps = {
+  /** Request context of the host's auth middleware (RLS as the user). */
+  context: PlatformAuthContext & { supabase: SupabaseClient };
+  /** Privileged client, used only for storage moves and bin rows. */
+  admin: () => Promise<SupabaseClient>;
+};
+
+export type MediaItem = {
+  name: string;
+  path: string;
+  size: number;
+  contentType: string | null;
+  updatedAt: string | null;
+  url: string;
+  uploadedBy?: string | null;
+  uploadedAt?: string | null;
+};
+
+export type TrashItem = {
+  id: string;
+  originalPath: string;
+  paths: string[];
+  trashPrefix: string;
+  size: number;
+  contentType: string | null;
+  deletedAt: string;
+  deletedByEmail: string | null;
+  usageCount: number;
+  url: string;
+};
+
+export type UploadMediaFile = {
+  name: string;
+  contentType: string;
+  bytes: number[];
+};
+
+const anyClient = (client: SupabaseClient) => client as unknown as any;
+
+/** All root-level file names currently in the library. */
+export async function listMediaNames(deps: MediaLibraryDeps): Promise<string[]> {
+  const storage = getMediaStorage(deps.context.supabase);
+  return (await storage.list()).map((f) => f.name);
+}
+
+/**
+ * Who uploaded what, taken from the append-only audit trail.
+ * Older assets predate upload auditing and simply have no entry.
+ */
+async function uploaderIndex(
+  deps: MediaLibraryDeps,
+): Promise<Record<string, { email: string | null; at: string }>> {
+  const map: Record<string, { email: string | null; at: string }> = {};
+  try {
+    const { data, error } = await anyClient(deps.context.supabase)
+      .from("audit_logs")
+      .select("actor_email, action, meta, created_at")
+      .eq("entity", "media")
+      .in("action", ["media.upload", "media.import"])
+      .order("created_at", { ascending: true })
+      .limit(5000);
+    if (error) return map;
+    for (const row of (data ?? []) as any[]) {
+      const paths: unknown = (row.meta as Record<string, unknown> | null)?.["paths"];
+      const list = Array.isArray(paths) ? paths : [];
+      for (const p of list) {
+        if (typeof p !== "string") continue;
+        map[p] = { email: row.actor_email ?? null, at: row.created_at };
+      }
+    }
+  } catch {
+    /* audit lookup is best-effort */
+  }
+  return map;
+}
+
+async function audit(
+  deps: MediaLibraryDeps,
+  action: string,
+  entityId: string,
+  meta: Record<string, unknown>,
+) {
+  const admin = await deps.admin();
+  await auditWriter(admin as never, deps.context, "media")(action, entityId, meta);
+}
+
+/** Library listing with the smaller responsive variants folded away. */
+export async function listMediaCore(deps: MediaLibraryDeps): Promise<MediaItem[]> {
+  const storage = getMediaStorage(deps.context.supabase);
+  const files = await storage.list();
+  const names = new Set(files.map((f) => f.name));
+  const visible = files.filter((f) => {
+    if (isSecondaryVariant(f.name)) return false;
+    const m = /^(.*)-1920\.webp$/i.exec(f.name);
+    if (m && names.has(`${m[1]}-2560.webp`)) return false;
+    return true;
+  });
+  const uploaders = await uploaderIndex(deps);
+  return visible.map((f) => {
+    const record =
+      uploaders[f.name] ??
+      variantSiblings(f.name)
+        .map((s) => uploaders[s])
+        .find(Boolean) ??
+      null;
+    return {
+      name: f.name,
+      path: f.name,
+      size: f.size,
+      contentType: f.contentType,
+      updatedAt: f.updatedAt,
+      url: storage.publicUrl(f.name),
+      uploadedBy: record?.email ?? null,
+      uploadedAt: record?.at ?? f.updatedAt,
+    };
+  });
+}
+
+/**
+ * Soft delete: move the primary file and all responsive variants into a hidden
+ * `trash/<id>/…` prefix and record the deletion. Nothing is erased here.
+ */
+export async function deleteMediaCore(
+  deps: MediaLibraryDeps,
+  input: { path: string },
+): Promise<{ ok: true; trashId: string }> {
+  const admin = await deps.admin();
+  const storage = getMediaStorage(admin);
+  const trashId = crypto.randomUUID();
+  const prefix = `trash/${trashId}`;
+
+  const candidates = [input.path, ...variantSiblings(input.path)];
+  const names = new Set(await listMediaNames(deps));
+  const targets = candidates.filter((p) => names.has(p));
+  if (targets.length === 0) throw new Error("File not found");
+
+  const listed = await storage.list();
+  const primaryMeta = listed.find((f) => f.name === input.path);
+
+  const moved: string[] = [];
+  try {
+    for (const p of targets) {
+      await storage.move(p, `${prefix}/${p}`);
+      moved.push(p);
+    }
+  } catch (err) {
+    for (const p of moved) {
+      await storage.move(`${prefix}/${p}`, p).catch(() => {});
+    }
+    throw err;
+  }
+
+  const { error: insErr } = await anyClient(admin)
+    .from("media_trash")
+    .insert({
+      id: trashId,
+      original_path: input.path,
+      paths: moved,
+      trash_prefix: prefix,
+      size_bytes: primaryMeta?.size ?? 0,
+      content_type: primaryMeta?.contentType ?? null,
+      deleted_by: deps.context.userId,
+      deleted_by_email: deps.context.claims?.email ?? null,
+    });
+  if (insErr) {
+    for (const p of moved) {
+      await storage.move(`${prefix}/${p}`, p).catch(() => {});
+    }
+    throw new Error(insErr.message);
+  }
+
+  await audit(deps, "media.trash", input.path, { files: moved.length });
+  return { ok: true, trashId };
+}
+
+/** Bin listing — staff may read it; only superadmins may purge. */
+export async function listTrashCore(deps: MediaLibraryDeps): Promise<TrashItem[]> {
+  const storage = getMediaStorage(deps.context.supabase);
+  const { data, error } = await anyClient(deps.context.supabase)
+    .from("media_trash")
+    .select("*")
+    .order("deleted_at", { ascending: false })
+    .limit(500);
+  if (error) throw new Error(error.message);
+  return ((data ?? []) as any[]).map((r) => ({
+    id: r.id,
+    originalPath: r.original_path,
+    paths: (r.paths ?? []) as string[],
+    trashPrefix: r.trash_prefix,
+    size: Number(r.size_bytes ?? 0),
+    contentType: r.content_type,
+    deletedAt: r.deleted_at,
+    deletedByEmail: r.deleted_by_email,
+    usageCount: Array.isArray(r.usage_snapshot) ? r.usage_snapshot.length : 0,
+    url: storage.publicUrl(`${r.trash_prefix}/${r.original_path}`),
+  }));
+}
+
+/** Restore every variant back to its original path, unless a name collision exists. */
+export async function restoreMediaCore(
+  deps: MediaLibraryDeps,
+  input: { id: string },
+): Promise<{ ok: true }> {
+  const admin = await deps.admin();
+  const storage = getMediaStorage(admin);
+  const { data: row, error } = await anyClient(admin)
+    .from("media_trash")
+    .select("*")
+    .eq("id", input.id)
+    .maybeSingle();
+  if (error) throw new Error(error.message);
+  if (!row) throw new Error("Bin entry not found");
+
+  const paths = (row.paths ?? []) as string[];
+  const prefix = row.trash_prefix as string;
+
+  const names = new Set(await listMediaNames(deps));
+  const clash = paths.find((p) => names.has(p));
+  if (clash) {
+    throw new Error(
+      `Cannot restore — a file named "${clash}" already exists in the library. Rename or remove it first.`,
+    );
+  }
+
+  const restored: string[] = [];
+  try {
+    for (const p of paths) {
+      await storage.move(`${prefix}/${p}`, p);
+      restored.push(p);
+    }
+  } catch (err) {
+    for (const p of restored) {
+      await storage.move(p, `${prefix}/${p}`).catch(() => {});
+    }
+    throw err;
+  }
+
+  await anyClient(admin).from("media_trash").delete().eq("id", input.id);
+  await audit(deps, "media.restore", row.original_path, { files: restored.length });
+  return { ok: true };
+}
+
+/** Permanent delete of one bin entry. Host must have asserted superadmin. */
+export async function purgeMediaCore(
+  deps: MediaLibraryDeps,
+  input: { id: string },
+): Promise<{ ok: true }> {
+  const admin = await deps.admin();
+  const storage = getMediaStorage(admin);
+  const { data: row, error } = await anyClient(admin)
+    .from("media_trash")
+    .select("*")
+    .eq("id", input.id)
+    .maybeSingle();
+  if (error) throw new Error(error.message);
+  if (!row) throw new Error("Bin entry not found");
+
+  const paths = (row.paths ?? []) as string[];
+  const prefix = row.trash_prefix as string;
+  await storage.remove(paths.map((p) => `${prefix}/${p}`));
+
+  const { error: delErr } = await anyClient(admin)
+    .from("media_trash")
+    .delete()
+    .eq("id", input.id);
+  if (delErr) throw new Error(delErr.message);
+
+  await audit(deps, "media.purge", row.original_path, { files: paths.length });
+  return { ok: true };
+}
+
+/** Empty the whole bin. Host must have asserted superadmin. */
+export async function emptyTrashCore(
+  deps: MediaLibraryDeps,
+): Promise<{ ok: true; purged: number }> {
+  const admin = await deps.admin();
+  const storage = getMediaStorage(admin);
+  const { data: rows, error } = await anyClient(admin).from("media_trash").select("*");
+  if (error) throw new Error(error.message);
+  let purged = 0;
+  for (const row of (rows ?? []) as any[]) {
+    const paths = (row.paths ?? []) as string[];
+    const prefix = row.trash_prefix as string;
+    await storage.remove(paths.map((p) => `${prefix}/${p}`));
+    await anyClient(admin).from("media_trash").delete().eq("id", row.id);
+    purged++;
+  }
+  await audit(deps, "media.empty_trash", "bin", { entries: purged });
+  return { ok: true, purged };
+}
+
+/** Public URL for one stored path. */
+export function signMediaUrlCore(
+  deps: MediaLibraryDeps,
+  input: { path: string },
+): { url: string } {
+  return { url: getMediaStorage(deps.context.supabase).publicUrl(input.path) };
+}
+
+/**
+ * Upload one or more already-optimized files. A name clash retries with a
+ * `-2`, `-3`, … suffix inserted before the responsive width, so a whole bundle
+ * keeps one consistent base name (`hero-2-1920.webp`).
+ */
+export async function uploadMediaBundleCore(
+  deps: MediaLibraryDeps,
+  input: { files: UploadMediaFile[]; upsert?: boolean },
+): Promise<{ urls: string[] }> {
+  const storage = getMediaStorage(deps.context.supabase);
+  const upsert = input.upsert ?? false;
+
+  const withSuffix = (name: string, n: number) => {
+    if (n <= 1) return name;
+    const m = /^(.*?)(-(?:480|768|1200|1920|2560))?(\.[^.]+)$/.exec(name);
+    if (!m) return `${name}-${n}`;
+    return `${m[1]}-${n}${m[2] ?? ""}${m[3]}`;
+  };
+
+  let uploaded: string[] = [];
+  for (let attempt = 1; attempt <= 20; attempt++) {
+    uploaded = [];
+    try {
+      for (const f of input.files) {
+        const name = withSuffix(f.name, attempt);
+        await storage.upload(name, new Uint8Array(f.bytes), f.contentType, { upsert });
+        uploaded.push(name);
+      }
+      break;
+    } catch (err) {
+      await storage.remove(uploaded).catch(() => {});
+      uploaded = [];
+      const msg = err instanceof Error ? err.message : String(err);
+      const exists = /already exists|Duplicate|409/i.test(msg);
+      if (upsert || !exists || attempt === 20) throw err;
+    }
+  }
+
+  await audit(deps, "media.upload", uploaded[0] ?? "upload", {
+    paths: uploaded,
+    count: uploaded.length,
+  });
+  return { urls: uploaded.map((n) => storage.publicUrl(n)) };
+}
+
+/**
+ * Upload a review (testimonial) image.
+ *
+ * The browser crops and re-encodes to WebP at the four responsive widths; every
+ * variant is independently validated here (magic number, real dimensions,
+ * aspect, compression ratio, byte ceiling) before anything is stored.
+ */
+export async function uploadReviewImageCore(
+  deps: MediaLibraryDeps,
+  input: { slug: string; variants: { width: number; data: string }[] },
+): Promise<{ url: string; path: string; bytes: number }> {
+  const slug = sanitizeReviewSlug(input.slug);
+  const provided = new Set(input.variants.map((v) => v.width));
+  for (const w of REVIEW_WIDTHS) {
+    if (!provided.has(w)) throw new Error(`Missing the ${w}px image variant.`);
+  }
+
+  const validated = input.variants.map((v) => ({
+    width: v.width,
+    file: validateReviewVariant(v.width, v.data),
+  }));
+
+  const storage = getMediaStorage(deps.context.supabase);
+
+  // Keep the uploaded filename (SEO); de-duplicate with a numeric suffix only.
+  const names = await listMediaNames(deps);
+  const takenBases = new Set<string>(
+    names.map((n) => n.replace(/-(?:480|768|1200|1920)\.webp$/i, "")),
+  );
+  const finalSlug = uniqueFileName(slug, takenBases);
+
+  const uploaded: string[] = [];
+  try {
+    for (const v of validated) {
+      const p = `${finalSlug}-${v.width}.webp`;
+      await storage.upload(p, v.file.bytes, "image/webp", { upsert: false });
+      uploaded.push(p);
+    }
+  } catch (err) {
+    if (uploaded.length) await storage.remove(uploaded).catch(() => {});
+    throw err;
+  }
+
+  const primaryPath = `${finalSlug}-1920.webp`;
+  const totalBytes = validated.reduce((n, v) => n + v.file.bytes.length, 0);
+  await audit(deps, "media.upload", primaryPath, { paths: uploaded });
+  return { url: storage.publicUrl(primaryPath), path: primaryPath, bytes: totalBytes };
+}
+
+/**
+ * Given cleaned base names, report which already exist and with which paths, so
+ * a bulk overwrite never adds a new asset by accident.
+ */
+export async function prepareMediaOverwriteCore(
+  deps: MediaLibraryDeps,
+  input: { bases: string[] },
+): Promise<Record<string, { exists: boolean; paths: string[] }>> {
+  const names = await listMediaNames(deps);
+  const result: Record<string, { exists: boolean; paths: string[] }> = {};
+  for (const base of input.bases) {
+    const prefix = `${base}-`;
+    const paths = names.filter(
+      (n) => n === base || n.startsWith(prefix) || n.startsWith(`${base}.`),
+    );
+    result[base] = { exists: paths.length > 0, paths };
+  }
+  return result;
+}
+
+/** Record a bulk overwrite run in the audit log. */
+export async function logMediaOverwriteCore(
+  deps: MediaLibraryDeps,
+  input: { paths: string[]; skipped: string[]; failed: string[] },
+): Promise<{ ok: true }> {
+  await audit(deps, "media.bulk_overwrite", "bulk", {
+    overwritten: input.paths,
+    skipped: input.skipped,
+    failed: input.failed,
+    count: input.paths.length,
+  });
+  return { ok: true };
+}

package/src/server/review-image-validate.ts

@@ -0,0 +1,103 @@
+/**
+ * Server-side validation for uploaded review images.
+ *
+ * The backoffice resizes/compresses review images in the browser, but the server
+ * never trusts that: every variant is decoded here, sniffed for a real WebP magic
+ * number, measured, and checked against the canonical review constraints
+ * (expected width, sane aspect bounds, height ceiling, byte ceiling) before
+ * anything is written to storage. Images keep their original aspect ratio;
+ * cropping is done at display time around the saved focus point.
+ */
+
+export const REVIEW_WIDTHS = [480, 768, 1200, 1920] as const;
+export const REVIEW_ASPECT = 16 / 10;
+/** Accepted aspect range for stored review images (portrait .. panorama). */
+const MIN_ASPECT = 0.2;
+const MAX_ASPECT = 5;
+const MAX_HEIGHT = 2400;
+/** Roughly 0.35 bytes per pixel — generous for WebP q0.8, tight enough to catch junk. */
+const MAX_BYTES_PER_PIXEL = 0.35;
+const MIN_BYTES = 256;
+export const MAX_VARIANT_BYTES = 2 * 1024 * 1024;
+
+export type ValidatedVariant = {
+  width: number;
+  height: number;
+  bytes: Uint8Array;
+};
+
+export function decodeBase64(data: string): Uint8Array {
+  const clean = data.includes(",") ? data.slice(data.indexOf(",") + 1) : data;
+  if (!/^[A-Za-z0-9+/=\s]+$/.test(clean)) throw new Error("Malformed image payload.");
+  const binary = atob(clean.replace(/\s+/g, ""));
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+/** Reads intrinsic dimensions from a WebP container (VP8 / VP8L / VP8X). */
+export function webpDimensions(bytes: Uint8Array): { width: number; height: number } | null {
+  if (bytes.length < 30) return null;
+  const tag = (o: number, s: string) =>
+    s.split("").every((c, i) => bytes[o + i] === c.charCodeAt(0));
+  if (!tag(0, "RIFF") || !tag(8, "WEBP")) return null;
+  const format = String.fromCharCode(bytes[12], bytes[13], bytes[14], bytes[15]);
+  if (format === "VP8 ") {
+    // Lossy: 3-byte frame tag + 3-byte sync code, then 14-bit width/height.
+    if (!(bytes[23] === 0x9d && bytes[24] === 0x01 && bytes[25] === 0x2a)) return null;
+    const width = (bytes[26] | (bytes[27] << 8)) & 0x3fff;
+    const height = (bytes[28] | (bytes[29] << 8)) & 0x3fff;
+    return { width, height };
+  }
+  if (format === "VP8L") {
+    if (bytes[20] !== 0x2f) return null;
+    const b = bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24);
+    return { width: (b & 0x3fff) + 1, height: ((b >> 14) & 0x3fff) + 1 };
+  }
+  if (format === "VP8X") {
+    const width = 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16));
+    const height = 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16));
+    return { width, height };
+  }
+  return null;
+}
+
+export function validateReviewVariant(width: number, raw: string): ValidatedVariant {
+  if (!(REVIEW_WIDTHS as readonly number[]).includes(width)) {
+    throw new Error(`Unexpected image variant width: ${width}.`);
+  }
+  const bytes = decodeBase64(raw);
+  if (bytes.length < MIN_BYTES) throw new Error("Image variant is empty or corrupt.");
+  if (bytes.length > MAX_VARIANT_BYTES) {
+    throw new Error(`Image variant ${width}px exceeds the 2 MB limit after compression.`);
+  }
+  const dims = webpDimensions(bytes);
+  if (!dims) throw new Error("Image variant is not a valid WebP file.");
+  if (dims.width > width) {
+    throw new Error(`Image variant ${width}px is larger than allowed (${dims.width}px).`);
+  }
+  if (dims.height > MAX_HEIGHT) {
+    throw new Error(`Image variant ${width}px is too tall (${dims.height}px).`);
+  }
+  const aspect = dims.width / dims.height;
+  if (aspect < MIN_ASPECT || aspect > MAX_ASPECT) {
+    throw new Error("Unsupported image proportions.");
+  }
+  if (bytes.length > dims.width * dims.height * MAX_BYTES_PER_PIXEL) {
+    throw new Error(`Image variant ${width}px is not compressed enough.`);
+  }
+  return { width: dims.width, height: dims.height, bytes };
+}
+
+export function sanitizeReviewSlug(slug: string): string {
+  const cleaned = slug
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  if (!cleaned) throw new Error("Invalid file name.");
+  // Keep the uploaded filename as-is (SEO) — no prefixes, no timestamps.
+  return cleaned;
+}