domma-cms 0.18.0 → 0.22.1

package/server/services/renderer.js

@@ -8,6 +8,7 @@ import {fileURLToPath} from 'url';
 import {getConfig} from '../config.js';
 import {getInjectionSnippets} from './plugins.js';
 import {applyTransforms} from './hooks.js';
+import {resolveLocation, resolveMenuDecorations} from './menus.js';
 
 const VALID_LAYOUT_WIDTHS = new Set(['narrow', 'normal', 'wide', 'full']);
 const CUSTOM_CSS_PATH = new URL('../../content/custom.css', import.meta.url).pathname;
@@ -55,17 +56,50 @@ function filterHiddenNavItems(nav) {
  * Render a page to a full HTML string.
  *
  * @param {object} page - Parsed page from content service
+ * @param {object} [opts]
+ * @param {string} [opts.baseUrl] - Absolute origin used for canonical URLs and
+ *   Open Graph `og:url`. Typically derived from the request (e.g.
+ *   `${request.protocol}://${request.hostname}`) by the route handler.
+ *   Falls back to `site.baseUrl` from config, then to no canonical at all.
+ * @param {object|null} [opts.user] - Authenticated user (`{role, additionalRoles}`)
+ *   or null for anonymous. Used to filter menu items gated by `visibility`.
  * @returns {Promise<string>}
  */
-export async function renderPage(page) {
-    const [template, site, navigation, presets, injection, customCss] = await Promise.all([
+export async function renderPage(page, opts = {}) {
+    const [template, site, presets, injection, customCss, navMenu, footerPrimary, footerLegal] = await Promise.all([
         getTemplate(),
         Promise.resolve(getConfig('site')),
-        Promise.resolve(getConfig('navigation')),
         Promise.resolve(getConfig('presets')),
         getInjectionSnippets(),
-        getCustomCss()
+        getCustomCss(),
+        resolveLocation('navbar',         opts.user || null),
+        resolveLocation('footer-primary', opts.user || null),
+        resolveLocation('footer-legal',   opts.user || null)
     ]);
+    const baseUrl = opts.baseUrl || site.baseUrl || '';
+
+    // Resolve live badge counts (countFrom) before the menus are injected as
+    // globals. Static badges/colours/pills pass through unchanged.
+    const [navItemsDecorated, footerPrimaryDecorated, footerLegalDecorated] = await Promise.all([
+        resolveMenuDecorations(navMenu ? navMenu.items : []),
+        resolveMenuDecorations(footerPrimary ? footerPrimary.items : []),
+        resolveMenuDecorations(footerLegal ? footerLegal.items : [])
+    ]);
+
+    // Compose the navigation object the public site script expects:
+    // brand from site.json.brand (parallel to adminBrand); items + variant +
+    // position + style from the menu mapped to the navbar slot.
+    // One-release fallback: if the navbar slot is unmapped, read the legacy
+    // navigation.json.bak file so a restored backup keeps working.
+    const navigation = navMenu
+        ? {
+            brand:    site.brand || {},
+            items:    navItemsDecorated,
+            variant:  navMenu.variant  || 'default',
+            position: navMenu.position || 'sticky',
+            ...(navMenu.style && {style: navMenu.style})
+        }
+        : (await readLegacyNavBackup()) || {brand: site.brand || {}, items: []};
 
     const preset = presets[page.layout] || presets['default'] || {};
 
@@ -85,6 +119,7 @@ export async function renderPage(page) {
     const seoTitle = escapeHtml(page.seo?.title || `${page.title}${site.seo?.titleSeparator || ' | '}${site.seo?.defaultTitle || site.title}`);
     const seoDescription = escapeHtml(page.seo?.description || site.seo?.defaultDescription || '');
     const ogImage = escapeHtml(page.seo?.image || site.seo?.defaultImage || '');
+    const seoTags = buildSeoTags({page, site, baseUrl, seoTitle, seoDescription, ogImage});
 
     const dconfig = page.dconfig || null;
     // Escape </script> to prevent injection via dconfig values in the inline script block
@@ -118,10 +153,19 @@ export async function renderPage(page) {
     const dommaTheme = site.baseTheme || activeTheme;
     const customThemeClass = site.baseTheme ? `dm-theme-${activeTheme}` : '';
 
+    // Compose window.__CMS_FOOTER__ from the menus mapped to footer-primary / footer-legal.
+    const footer = {
+        primary:   footerPrimaryDecorated,
+        legal:     footerLegalDecorated,
+        copyright: site.footer?.copyright || ''
+    };
+    const footerJson = JSON.stringify(footer).replace(/<\/script>/gi, '<\\/script>');
+
     const vars = {
         seoTitle,
         seoDescription,
         ogImage,
+        seoTags,
         title: page.title,
         html: page.html,
         breadcrumbsHtml,
@@ -137,6 +181,7 @@ export async function renderPage(page) {
         showFooter: preset.footer !== false,
         showSidebar: preset.sidebar === true || page.sidebar === true,
         navJson: JSON.stringify(filterHiddenNavItems(navigation)).replace(/<\/script>/gi, '<\\/script>'),
+        footerScript: footerJson ? `window.__CMS_FOOTER__ = ${footerJson};` : '',
         siteJson: JSON.stringify(Object.assign(
             {
                 title: site.title,
@@ -170,6 +215,42 @@ export async function renderPage(page) {
     return applyTransforms('render:afterRender', html, {page});
 }
 
+/**
+ * Build the ordered list of breadcrumb items for a page.
+ * Returns an empty array on the home page (or when the path has no segments).
+ *
+ * Used by both the visual breadcrumb renderer and the BreadcrumbList JSON-LD
+ * emitter, so the structured data and the visible trail stay in sync.
+ *
+ * @param {object} page - Parsed page object with urlPath, title
+ * @param {object} site - Site config (uses breadcrumbs.homeLabel)
+ * @returns {Array<{name: string, urlPath: string}>}
+ */
+function buildBreadcrumbItems(page, site) {
+    const urlPath = page.urlPath || '/';
+    if (urlPath === '/') return [];
+
+    const segments = urlPath.split('/').filter(Boolean);
+    if (!segments.length) return [];
+
+    const homeLabel = site?.breadcrumbs?.homeLabel || 'Home';
+    const items = [{name: homeLabel, urlPath: '/'}];
+
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        items.push({
+            name: toTitleCase(segments[i]),
+            urlPath: '/' + segments.slice(0, i + 1).join('/')
+        });
+    }
+
+    items.push({
+        name: page.title || toTitleCase(segments[segments.length - 1]),
+        urlPath
+    });
+
+    return items;
+}
+
 /**
  * Build breadcrumbs HTML for a page.
  * Returns an empty string if breadcrumbs are disabled globally or per-page.
@@ -183,13 +264,8 @@ function buildBreadcrumbsHtml(page, site) {
     if (!cfg.enabled) return '';
     if (page.breadcrumbs === false) return '';
 
-    const urlPath = page.urlPath || '/';
-    // Don't render breadcrumbs on the home page
-    if (urlPath === '/') return '';
-
-    const homeLabel = cfg.homeLabel || 'Home';
-    const segments = urlPath.split('/').filter(Boolean);
-    if (!segments.length) return '';
+    const items = buildBreadcrumbItems(page, site);
+    if (!items.length) return '';
 
     // Build fixed-position inline style from corner + offsets
     const pos = (cfg.position || 'TL').toUpperCase();
@@ -200,21 +276,16 @@ function buildBreadcrumbsHtml(page, site) {
         pos.includes('L') ? `left:${offsetX}px` : `right:${offsetX}px`
     ].join(';');
 
-    const crumbs = [];
-
     const homeIcon = '<svg class="dm-breadcrumbs-home-icon" width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><polyline points="9 22 9 12 15 12 15 22"/></svg>';
-    // Home crumb
-    crumbs.push(`<a href="/" class="dm-breadcrumbs-item dm-breadcrumbs-link">${homeIcon}${escapeHtml(homeLabel)}</a>`);
-
-    // Middle crumbs (each intermediate path segment)
-    for (let i = 0; i < segments.length - 1; i++) {
-        const href = '/' + segments.slice(0, i + 1).join('/');
-        const label = toTitleCase(segments[i]);
-        crumbs.push(`<a href="${href}" class="dm-breadcrumbs-item dm-breadcrumbs-link">${escapeHtml(label)}</a>`);
-    }
 
-    // Last crumb — current page title, no link
-    crumbs.push(`<span class="dm-breadcrumbs-item dm-breadcrumbs-current" aria-current="page">${escapeHtml(page.title || toTitleCase(segments[segments.length - 1]))}</span>`);
+    const crumbs = items.map((item, i) => {
+        const isLast = i === items.length - 1;
+        if (isLast) {
+            return `<span class="dm-breadcrumbs-item dm-breadcrumbs-current" aria-current="page">${escapeHtml(item.name)}</span>`;
+        }
+        const icon = i === 0 ? homeIcon : '';
+        return `<a href="${item.urlPath}" class="dm-breadcrumbs-item dm-breadcrumbs-link">${icon}${escapeHtml(item.name)}</a>`;
+    });
 
     const sep = '<span class="dm-breadcrumbs-separator" aria-hidden="true">›</span>';
     return `<nav class="dm-breadcrumbs" aria-label="Breadcrumb" style="${posStyle}">${crumbs.join(sep)}</nav>`;
@@ -224,6 +295,88 @@ function toTitleCase(str) {
     return str.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 }
 
+/**
+ * Build the consolidated SEO `<meta>` tag block: canonical link, Open Graph,
+ * Twitter cards, JSON-LD, and a noindex hint when requested.
+ *
+ * All values are HTML-escaped at the call site (seoTitle/Description/ogImage)
+ * or here (canonicalUrl). JSON-LD is JSON.stringify'd and `</script>` is
+ * escaped to prevent breaking out of the script context.
+ *
+ * @param {object} args
+ * @param {object} args.page - Parsed page (urlPath, seo, title)
+ * @param {object} args.site - Site config (seo defaults)
+ * @param {string} args.baseUrl - Absolute origin for this request, derived by
+ *   the route handler. Pass empty string to skip canonical/og:url emission.
+ * @param {string} args.seoTitle - Already HTML-escaped
+ * @param {string} args.seoDescription - Already HTML-escaped
+ * @param {string} args.ogImage - Already HTML-escaped (may be empty)
+ * @returns {string}
+ */
+function buildSeoTags({page, site, baseUrl, seoTitle, seoDescription, ogImage}) {
+    const origin = (baseUrl || '').toString().trim().replace(/\/+$/, '');
+    const urlPath = page.urlPath || '/';
+    const canonicalUrl = origin ? escapeHtml(`${origin}${urlPath}`) : '';
+    const ogType = escapeHtml(page.seo?.ogType || 'article');
+    const siteName = escapeHtml(site.title || '');
+    const twitterHandle = escapeHtml(site.social?.twitter || '');
+    const noindex = page.seo?.noindex === true;
+
+    const tags = [];
+    if (canonicalUrl) tags.push(`<link rel="canonical" href="${canonicalUrl}">`);
+    if (noindex) tags.push('<meta name="robots" content="noindex, nofollow">');
+
+    tags.push(`<meta property="og:title" content="${seoTitle}">`);
+    tags.push(`<meta property="og:description" content="${seoDescription}">`);
+    tags.push(`<meta property="og:type" content="${ogType}">`);
+    if (siteName) tags.push(`<meta property="og:site_name" content="${siteName}">`);
+    if (canonicalUrl) tags.push(`<meta property="og:url" content="${canonicalUrl}">`);
+    if (ogImage) tags.push(`<meta property="og:image" content="${ogImage}">`);
+
+    tags.push(`<meta name="twitter:card" content="${ogImage ? 'summary_large_image' : 'summary'}">`);
+    tags.push(`<meta name="twitter:title" content="${seoTitle}">`);
+    tags.push(`<meta name="twitter:description" content="${seoDescription}">`);
+    if (ogImage) tags.push(`<meta name="twitter:image" content="${ogImage}">`);
+    if (twitterHandle) tags.push(`<meta name="twitter:site" content="${twitterHandle}">`);
+
+    // JSON-LD WebPage schema — gives search engines a structured summary.
+    // Omit `url` when no baseUrl, since a relative URL in JSON-LD is invalid.
+    const jsonLd = {
+        '@context': 'https://schema.org',
+        '@type': 'WebPage',
+        name: page.title || '',
+        description: page.seo?.description || site.seo?.defaultDescription || ''
+    };
+    if (canonicalUrl) jsonLd.url = origin + urlPath;
+    if (page.seo?.image || site.seo?.defaultImage) {
+        jsonLd.image = page.seo?.image || site.seo?.defaultImage;
+    }
+    const jsonLdString = JSON.stringify(jsonLd).replace(/<\/script>/gi, '<\\/script>');
+    tags.push(`<script type="application/ld+json">${jsonLdString}</script>`);
+
+    // BreadcrumbList JSON-LD — emit whenever the page has a non-trivial path
+    // and an origin is known (Schema.org requires absolute URLs in `item`).
+    // Independent of the visual breadcrumb setting so SERPs can show the trail
+    // even when the on-page nav hides it.
+    const breadcrumbItems = buildBreadcrumbItems(page, site);
+    if (origin && breadcrumbItems.length > 1) {
+        const breadcrumbJsonLd = {
+            '@context': 'https://schema.org',
+            '@type': 'BreadcrumbList',
+            itemListElement: breadcrumbItems.map((item, i) => ({
+                '@type': 'ListItem',
+                position: i + 1,
+                name: item.name,
+                item: origin + item.urlPath
+            }))
+        };
+        const breadcrumbString = JSON.stringify(breadcrumbJsonLd).replace(/<\/script>/gi, '<\\/script>');
+        tags.push(`<script type="application/ld+json">${breadcrumbString}</script>`);
+    }
+
+    return tags.join('\n    ');
+}
+
 function escapeHtml(str) {
     return String(str)
         .replace(/&/g, '&amp;')
@@ -288,19 +441,50 @@ function buildFontVars(fontFamily, fontSize) {
  *
  * @param {string} templatePath - Absolute path to the plugin HTML fragment
  * @param {object} data - Token replacement map; keys become {{key}} placeholders
- * @param {object} seoMeta - Optional SEO overrides: { title, description, ogImage }
+ * @param {object} seoMeta - Optional SEO overrides: { title, description, ogImage,
+ *   urlPath, ogType, noindex, baseUrl, user }. Pass `baseUrl` (derived from the
+ *   request) to populate canonical and og:url tags. Pass `user` (`{role, additionalRoles}`
+ *   or null) so menu items gated by `visibility` are filtered correctly; blog
+ *   callers currently default to anonymous (null).
  * @returns {Promise<string>}
  */
 export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
-    const [fragment, template, site, navigation, injection, customCss] = await Promise.all([
+    const user = seoMeta.user || null;
+    const [fragment, template, site, injection, customCss, navMenu, footerPrimary, footerLegal] = await Promise.all([
         fs.readFile(templatePath, 'utf8'),
         getTemplate(),
         Promise.resolve(getConfig('site')),
-        Promise.resolve(getConfig('navigation')),
         getInjectionSnippets(),
-        getCustomCss()
+        getCustomCss(),
+        resolveLocation('navbar',         user),
+        resolveLocation('footer-primary', user),
+        resolveLocation('footer-legal',   user)
+    ]);
+    const baseUrl = seoMeta.baseUrl || site.baseUrl || '';
+
+    // Resolve live badge counts (countFrom) before the menus are injected as
+    // globals. Static badges/colours/pills pass through unchanged.
+    const [navItemsDecorated, footerPrimaryDecorated, footerLegalDecorated] = await Promise.all([
+        resolveMenuDecorations(navMenu ? navMenu.items : []),
+        resolveMenuDecorations(footerPrimary ? footerPrimary.items : []),
+        resolveMenuDecorations(footerLegal ? footerLegal.items : [])
     ]);
 
+    // Compose the navigation object the public site script expects:
+    // brand from site.json.brand (parallel to adminBrand); items + variant +
+    // position + style from the menu mapped to the navbar slot.
+    // One-release fallback: if the navbar slot is unmapped, read the legacy
+    // navigation.json.bak file so a restored backup keeps working.
+    const navigation = navMenu
+        ? {
+            brand:    site.brand || {},
+            items:    navItemsDecorated,
+            variant:  navMenu.variant  || 'default',
+            position: navMenu.position || 'sticky',
+            ...(navMenu.style && {style: navMenu.style})
+        }
+        : (await readLegacyNavBackup()) || {brand: site.brand || {}, items: []};
+
     // Replace {{key}} tokens in the plugin fragment with data values
     const renderedFragment = fragment.replace(/\{\{(\w+)\}\}/g, (_, key) => {
         const val = data[key];
@@ -312,17 +496,18 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
     const seoDescription = escapeHtml(seoMeta.description ?? site.seo?.defaultDescription ?? '');
     const ogImage = escapeHtml(seoMeta.ogImage ?? '');
 
-    const ogType = escapeHtml(seoMeta.ogType ?? 'website');
-    const ogTags = [
-        `<meta property="og:title" content="${seoTitle}">`,
-        `<meta property="og:description" content="${seoDescription}">`,
-        `<meta property="og:type" content="${ogType}">`,
-        ogImage ? `<meta property="og:image" content="${ogImage}">` : '',
-        `<meta name="twitter:card" content="${ogImage ? 'summary_large_image' : 'summary'}">`,
-        `<meta name="twitter:title" content="${seoTitle}">`,
-        `<meta name="twitter:description" content="${seoDescription}">`,
-        ogImage ? `<meta name="twitter:image" content="${ogImage}">` : ''
-    ].filter(Boolean).join('\n');
+    // Plugin fragments use the unified SEO builder with a synthetic page object.
+    const syntheticPage = {
+        urlPath: seoMeta.urlPath || '/',
+        title: seoMeta.title || site.title || '',
+        seo: {
+            description: seoMeta.description,
+            image: seoMeta.ogImage,
+            ogType: seoMeta.ogType || 'website',
+            noindex: seoMeta.noindex === true
+        }
+    };
+    const seoTags = buildSeoTags({page: syntheticPage, site, baseUrl, seoTitle, seoDescription, ogImage});
 
     const {fontLink, fontOverride} = buildFontVars(site.fontFamily, site.fontSize);
     const fontStyleTag = fontOverride ? `<style>${fontOverride}</style>` : '';
@@ -336,10 +521,19 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
     const dommaTheme = site.baseTheme || activeTheme;
     const customThemeClass = site.baseTheme ? `dm-theme-${activeTheme}` : '';
 
+    // Compose window.__CMS_FOOTER__ from the menus mapped to footer-primary / footer-legal.
+    const footer = {
+        primary:   footerPrimaryDecorated,
+        legal:     footerLegalDecorated,
+        copyright: site.footer?.copyright || ''
+    };
+    const footerJson = JSON.stringify(footer).replace(/<\/script>/gi, '<\\/script>');
+
     const vars = {
         seoTitle,
         seoDescription,
         ogImage,
+        seoTags,
         title: seoTitle,
         html: renderedFragment,
         breadcrumbsHtml: '',
@@ -355,6 +549,7 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
         showFooter: true,
         showSidebar: false,
         navJson: JSON.stringify(filterHiddenNavItems(navigation)).replace(/<\/script>/gi, '<\\/script>'),
+        footerScript: footerJson ? `window.__CMS_FOOTER__ = ${footerJson};` : '',
         siteJson: JSON.stringify({
             title: site.title,
             footer: site.footer
@@ -365,7 +560,7 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
                 : site.footer,
             social: site.social || null
         }).replace(/<\/script>/gi, '<\\/script>'),
-        headInject: [ogTags, injection.head, navbarFontLink].filter(Boolean).join('\n'),
+        headInject: [injection.head, navbarFontLink].filter(Boolean).join('\n'),
         headInjectLate: [injection.headLate, customCssTag, navbarStyleTag].filter(Boolean).join('\n'),
         bodyEndInject: [
             injection.bodyEnd,
@@ -379,6 +574,24 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
     return interpolate(template, vars);
 }
 
+/**
+ * Read config/navigation.json.bak as a one-release fallback when no menu is
+ * mapped to the navbar slot. Returns null when the .bak is missing.
+ *
+ * @returns {Promise<object|null>}
+ */
+async function readLegacyNavBackup() {
+    try {
+        const here = fileURLToPath(import.meta.url);
+        const bak  = path.resolve(path.dirname(here), '..', '..', 'config', 'navigation.json.bak');
+        const raw  = await fs.readFile(bak, 'utf8');
+        console.warn('[menus] navbar location unmapped — falling back to navigation.json.bak (deprecated)');
+        return JSON.parse(raw);
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Simple template interpolation.
  * Handles {{variable}}, {{#if flag}}...{{/if}}.

package/server/services/roles.js

@@ -118,7 +118,12 @@ function buildCache(entries) {
 
     for (const entry of entries) {
         const d = entry.data;
-        roleMap.set(d.name, {label: d.label, level: d.level, badgeClass: d.badgeClass || ''});
+        roleMap.set(d.name, {
+            label: d.label,
+            level: d.level,
+            badgeClass: d.badgeClass || '',
+            ...(d.meta != null && {meta: d.meta})
+        });
         rawPermissionsMap.set(d.name, d.permissions || []);
         for (const perm of (d.permissions || [])) {
             if (perm.includes('.')) {

package/server/services/rowAccess.js

@@ -2,18 +2,37 @@
  * Row-Level Access Control
  *
  * Shared helpers for scoping Actions and Views to specific entries based on
- * ownership or a foreign-key field match.
+ * ownership, a foreign-key field match, or a referenced entry's ownership.
  *
  * rowLevel shape (stored in action/view access config):
- *   {
- *     mode:    'owner' | 'field',
- *     field:   'assigned_to',   // required when mode === 'field'
- *     userKey: 'id'             // user property to match (default: 'id')
- *   }
+ *
+ *   { mode: 'owner' }
+ *     Entry's `meta.createdBy` must equal `user[userKey]` (defaults to user.id).
+ *     Standard "you only see entries you created" pattern.
+ *
+ *   { mode: 'field', field: 'assignedTo' }
+ *     Entry's `data.<field>` must equal `user[userKey]`. Use for explicit
+ *     assignment (e.g. tickets routed to a specific user id).
+ *
+ *   { mode: 'reference', field: 'jobId', targetCollection: 'jobs', targetField: 'createdBy' }
+ *     Resolve `data.<field>` against `targetCollection` and check that target
+ *     entry's `meta.createdBy` (or `data.<targetField>` if `targetField` is a
+ *     data field name) equals `user[userKey]`. This is "user can access THIS
+ *     entry because they own the entry it points at" — the recruiter/employer
+ *     pattern: applications scoped to the jobs the user posted.
+ *
+ *     `targetField` accepts:
+ *       - 'createdBy' (default) → matches against target's meta.createdBy
+ *       - any other string      → matches against target's data.<targetField>
+ *
+ * All modes accept an optional `userKey` (default 'id') to control which
+ * user property is matched.
  *
  * Admin users (role level 0) always bypass row-level checks.
  */
 import {getRoleLevel} from './roles.js';
+import {getEffectiveLevel} from './userRoles.js';
+import {getAdapter} from './adapterRegistry.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -38,7 +57,9 @@ function resolveUserValue(user, userKey = 'id') {
  */
 function isAdmin(user) {
     if (!user?.role) return false;
-    return getRoleLevel(user.role) === 0;
+    // Use effective level so a user with "additionalRoles: ['super-admin']"
+    // bypasses row-level checks even when their primary role is lower-tier.
+    return getEffectiveLevel(user) === 0;
 }
 
 // ---------------------------------------------------------------------------
@@ -47,19 +68,29 @@ function isAdmin(user) {
 
 /**
  * Check whether a user may access a specific entry under row-level rules.
- * Returns `true` when: rowLevel is absent, user is admin, or the entry
- * satisfies the configured mode.
+ *
+ * **Async because `mode: 'reference'` requires loading the referenced entry
+ * to compare its owner.** Callers MUST `await` the result.
+ *
+ * Returns `true` when: rowLevel is absent, user is admin, the entry directly
+ * satisfies an `owner`/`field` rule, OR the entry's referenced target
+ * satisfies the `reference` rule. Returns `false` only when a rule is set
+ * AND the entry fails it. Misconfigured rules (missing fields, unknown
+ * targets) fail closed — return `false` to avoid leaking data through typos.
  *
  * @param {object}      entry    - Full entry object ({ id, data, meta })
  * @param {object|null} user     - Authenticated user object
  * @param {object|null} rowLevel - rowLevel config from action/view access
- * @returns {boolean}
+ * @param {object}      [opts]
+ * @param {Function}    [opts.adapterResolver] - Optional async (slug) → adapter — for tests
+ * @returns {Promise<boolean>}
  */
-export function checkEntryAccess(entry, user, rowLevel) {
+export async function checkEntryAccess(entry, user, rowLevel, opts = {}) {
     if (!rowLevel) return true;
     if (isAdmin(user)) return true;
 
     const userVal = resolveUserValue(user, rowLevel.userKey);
+    if (userVal == null) return false;
 
     if (rowLevel.mode === 'owner') {
         return entry?.meta?.createdBy === userVal;
@@ -67,11 +98,47 @@ export function checkEntryAccess(entry, user, rowLevel) {
 
     if (rowLevel.mode === 'field') {
         const field = rowLevel.field;
-        if (!field) return true; // misconfigured — be permissive
+        if (!field) return false;     // misconfigured — fail closed
         return entry?.data?.[field] === userVal;
     }
 
-    return true; // unknown mode — be permissive
+    if (rowLevel.mode === 'reference') {
+        const field            = rowLevel.field;
+        const targetCollection = rowLevel.targetCollection;
+        const targetField      = rowLevel.targetField || 'createdBy';
+        if (!field || !targetCollection) return false;       // misconfigured — fail closed
+
+        // The referenced id lives at data.<field>. Arrays of ids are supported
+        // — access is granted when ANY of the targets is owned by the user
+        // (e.g. "I can see this entry because I own at least one of its parents").
+        const raw = entry?.data?.[field];
+        if (raw == null || raw === '') return false;
+        const ids = Array.isArray(raw) ? raw.map(String) : [String(raw)];
+
+        const resolver = opts.adapterResolver || getAdapter;
+        let adapter;
+        try {
+            adapter = await resolver(targetCollection);
+        } catch {
+            return false;
+        }
+
+        for (const id of ids) {
+            try {
+                const target = await adapter.get(targetCollection, id);
+                if (!target) continue;                       // dangling reference — skip
+                const value = targetField === 'createdBy'
+                    ? target.meta?.createdBy
+                    : target.data?.[targetField];
+                if (value === userVal) return true;
+            } catch {
+                /* continue probing other ids on adapter error */
+            }
+        }
+        return false;
+    }
+
+    return false;     // unknown mode — fail closed
 }
 
 /**
@@ -80,6 +147,10 @@ export function checkEntryAccess(entry, user, rowLevel) {
  *
  * The returned object is ready to use as `{ $match: buildRowLevelMatch(...) }`.
  *
+ * Note: `mode: 'reference'` can't be expressed as a flat $match without a
+ * `$lookup` — for that mode this function returns `null` and callers must
+ * fall back to per-entry `checkEntryAccess()` filtering (slower but correct).
+ *
  * @param {object|null} user
  * @param {object|null} rowLevel
  * @returns {object|null}
@@ -100,5 +171,7 @@ export function buildRowLevelMatch(user, rowLevel) {
         return {[`data.${field}`]: userVal};
     }
 
+    // 'reference' mode needs a join — caller should use checkEntryAccess()
+    // per-entry instead. Return null so the upstream code knows to do that.
     return null;
 }