domma-cms 0.23.0 → 0.25.0

package/server/services/email.js

@@ -1,167 +1,167 @@
-/**
- * Core Email Utility
- * Nodemailer transport factory and generic form email sending utility.
- */
-import nodemailer from 'nodemailer';
-
-let lastSendResult = null;
-
-/**
- * Return the most recent email send result, or null if no send has occurred.
- *
- * @returns {{ ok: boolean, at: string, info: string|null } | null}
- */
-export function getLastSendResult() {
-    return lastSendResult;
-}
-
-/**
- * Record the outcome of an email send for health reporting.
- *
- * @param {boolean} ok
- * @param {string|null} info
- * @returns {void}
- */
-function recordSendResult(ok, info) {
-    lastSendResult = {
-        ok,
-        at: new Date().toISOString(),
-        info: info || null
-    };
-}
-
-/**
- * Escape HTML special characters for safe use in email bodies.
- *
- * @param {string} str
- * @returns {string}
- */
-export function escapeHtml(str) {
-    return String(str)
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
-
-/**
- * Create a nodemailer transport.
- * Falls back to an Ethereal test account when no SMTP host is configured.
- *
- * @param {{ host: string, port: number, secure: boolean, user: string, pass: string }} smtp
- * @returns {Promise<import('nodemailer').Transporter>}
- * @throws {Error} If Ethereal test account creation fails.
- */
-export async function createTransport(smtp) {
-    if (smtp?.host) {
-        return nodemailer.createTransport({
-            host: smtp.host,
-            port: smtp.port || 587,
-            secure: smtp.secure || false,
-            auth: smtp.user ? { user: smtp.user, pass: smtp.pass } : undefined,
-            tls: { rejectUnauthorized: false }
-        });
-    }
-
-    // No SMTP configured — use Ethereal for dev/demo
-    const testAccount = await nodemailer.createTestAccount();
-    console.log('[email] No SMTP configured. Using Ethereal test account:', testAccount.user);
-    return nodemailer.createTransport({
-        host: 'smtp.ethereal.email',
-        port: 587,
-        secure: false,
-        auth: { user: testAccount.user, pass: testAccount.pass }
-    });
-}
-
-/**
- * Send a generic transactional email.
- *
- * @param {import('nodemailer').Transporter} transport
- * @param {{ from: string, fromName: string, to: string, subject: string, html: string, text: string }} opts
- * @returns {Promise<void>}
- * @throws {Error} If sending the email fails.
- */
-export async function sendEmail(transport, {from, fromName, to, subject, html, text}) {
-    try {
-        const info = await transport.sendMail({
-            from: `"${fromName}" <${from}>`,
-            to,
-            subject,
-            text,
-            html
-        });
-        recordSendResult(true, info.messageId);
-
-        const previewUrl = nodemailer.getTestMessageUrl(info);
-        if (previewUrl) {
-            console.log('[email] Preview URL:', previewUrl);
-        }
-        return info;
-    } catch (err) {
-        recordSendResult(false, err.message);
-        throw err;
-    }
-}
-
-/**
- * Send an HTML + plain-text form submission notification email.
- * Builds a generic table of field→value pairs from the submitted data.
- *
- * @param {import('nodemailer').Transporter} transport
- * @param {{ from: string, fromName: string, to: string, subject: string, formTitle: string, fields: Array<{name: string, label: string}>, data: Record<string, unknown> }} opts
- * @returns {Promise<void>}
- * @throws {Error} If sending the email fails.
- */
-export async function sendFormEmail(transport, { from, fromName, to, subject, formTitle, fields, data }) {
-    const rows = fields.map(field => {
-        const val  = data[field.name] ?? '';
-        const safe = escapeHtml(String(val)).replace(/\n/g, '<br>');
-        const safeLabel = escapeHtml(field.label || field.name);
-        return `
-        <tr>
-            <td style="padding:8px 12px;font-weight:600;background:#f9f9f9;border:1px solid #eee;white-space:nowrap;vertical-align:top;">${safeLabel}</td>
-            <td style="padding:8px 12px;border:1px solid #eee;vertical-align:top;">${safe}</td>
-        </tr>`.trim();
-    }).join('\n');
-
-    const plainRows = fields.map(field => {
-        const val = data[field.name] ?? '';
-        return `${field.label || field.name}: ${val}`;
-    }).join('\n');
-
-    const html = `
-<!DOCTYPE html>
-<html>
-<body style="font-family:sans-serif;max-width:640px;margin:0 auto;padding:20px;">
-    <h2 style="color:#333;margin-bottom:4px;">New Form Submission</h2>
-    <p style="color:#888;margin-top:0;font-size:.9rem;">${escapeHtml(formTitle)}</p>
-    <table style="width:100%;border-collapse:collapse;margin-top:16px;">
-        ${rows}
-    </table>
-</body>
-</html>`.trim();
-
-    const text = `New form submission: ${formTitle}\n\n${plainRows}`;
-
-    try {
-        const info = await transport.sendMail({
-            from: `"${fromName}" <${from}>`,
-            to,
-            subject,
-            text,
-            html
-        });
-        recordSendResult(true, info.messageId);
-
-        const previewUrl = nodemailer.getTestMessageUrl(info);
-        if (previewUrl) {
-            console.log('[email] Preview URL:', previewUrl);
-        }
-        return info;
-    } catch (err) {
-        recordSendResult(false, err.message);
-        throw err;
-    }
-}
+/**
+ * Core Email Utility
+ * Nodemailer transport factory and generic form email sending utility.
+ */
+import nodemailer from 'nodemailer';
+
+let lastSendResult = null;
+
+/**
+ * Return the most recent email send result, or null if no send has occurred.
+ *
+ * @returns {{ ok: boolean, at: string, info: string|null } | null}
+ */
+export function getLastSendResult() {
+    return lastSendResult;
+}
+
+/**
+ * Record the outcome of an email send for health reporting.
+ *
+ * @param {boolean} ok
+ * @param {string|null} info
+ * @returns {void}
+ */
+function recordSendResult(ok, info) {
+    lastSendResult = {
+        ok,
+        at: new Date().toISOString(),
+        info: info || null
+    };
+}
+
+/**
+ * Escape HTML special characters for safe use in email bodies.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function escapeHtml(str) {
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+/**
+ * Create a nodemailer transport.
+ * Falls back to an Ethereal test account when no SMTP host is configured.
+ *
+ * @param {{ host: string, port: number, secure: boolean, user: string, pass: string }} smtp
+ * @returns {Promise<import('nodemailer').Transporter>}
+ * @throws {Error} If Ethereal test account creation fails.
+ */
+export async function createTransport(smtp) {
+    if (smtp?.host) {
+        return nodemailer.createTransport({
+            host: smtp.host,
+            port: smtp.port || 587,
+            secure: smtp.secure || false,
+            auth: smtp.user ? { user: smtp.user, pass: smtp.pass } : undefined,
+            tls: { rejectUnauthorized: false }
+        });
+    }
+
+    // No SMTP configured — use Ethereal for dev/demo
+    const testAccount = await nodemailer.createTestAccount();
+    console.log('[email] No SMTP configured. Using Ethereal test account:', testAccount.user);
+    return nodemailer.createTransport({
+        host: 'smtp.ethereal.email',
+        port: 587,
+        secure: false,
+        auth: { user: testAccount.user, pass: testAccount.pass }
+    });
+}
+
+/**
+ * Send a generic transactional email.
+ *
+ * @param {import('nodemailer').Transporter} transport
+ * @param {{ from: string, fromName: string, to: string, subject: string, html: string, text: string }} opts
+ * @returns {Promise<void>}
+ * @throws {Error} If sending the email fails.
+ */
+export async function sendEmail(transport, {from, fromName, to, subject, html, text}) {
+    try {
+        const info = await transport.sendMail({
+            from: `"${fromName}" <${from}>`,
+            to,
+            subject,
+            text,
+            html
+        });
+        recordSendResult(true, info.messageId);
+
+        const previewUrl = nodemailer.getTestMessageUrl(info);
+        if (previewUrl) {
+            console.log('[email] Preview URL:', previewUrl);
+        }
+        return info;
+    } catch (err) {
+        recordSendResult(false, err.message);
+        throw err;
+    }
+}
+
+/**
+ * Send an HTML + plain-text form submission notification email.
+ * Builds a generic table of field→value pairs from the submitted data.
+ *
+ * @param {import('nodemailer').Transporter} transport
+ * @param {{ from: string, fromName: string, to: string, subject: string, formTitle: string, fields: Array<{name: string, label: string}>, data: Record<string, unknown> }} opts
+ * @returns {Promise<void>}
+ * @throws {Error} If sending the email fails.
+ */
+export async function sendFormEmail(transport, { from, fromName, to, subject, formTitle, fields, data }) {
+    const rows = fields.map(field => {
+        const val  = data[field.name] ?? '';
+        const safe = escapeHtml(String(val)).replace(/\n/g, '<br>');
+        const safeLabel = escapeHtml(field.label || field.name);
+        return `
+        <tr>
+            <td style="padding:8px 12px;font-weight:600;background:#f9f9f9;border:1px solid #eee;white-space:nowrap;vertical-align:top;">${safeLabel}</td>
+            <td style="padding:8px 12px;border:1px solid #eee;vertical-align:top;">${safe}</td>
+        </tr>`.trim();
+    }).join('\n');
+
+    const plainRows = fields.map(field => {
+        const val = data[field.name] ?? '';
+        return `${field.label || field.name}: ${val}`;
+    }).join('\n');
+
+    const html = `
+<!DOCTYPE html>
+<html>
+<body style="font-family:sans-serif;max-width:640px;margin:0 auto;padding:20px;">
+    <h2 style="color:#333;margin-bottom:4px;">New Form Submission</h2>
+    <p style="color:#888;margin-top:0;font-size:.9rem;">${escapeHtml(formTitle)}</p>
+    <table style="width:100%;border-collapse:collapse;margin-top:16px;">
+        ${rows}
+    </table>
+</body>
+</html>`.trim();
+
+    const text = `New form submission: ${formTitle}\n\n${plainRows}`;
+
+    try {
+        const info = await transport.sendMail({
+            from: `"${fromName}" <${from}>`,
+            to,
+            subject,
+            text,
+            html
+        });
+        recordSendResult(true, info.messageId);
+
+        const previewUrl = nodemailer.getTestMessageUrl(info);
+        if (previewUrl) {
+            console.log('[email] Preview URL:', previewUrl);
+        }
+        return info;
+    } catch (err) {
+        recordSendResult(false, err.message);
+        throw err;
+    }
+}

package/server/services/permissionRegistry.js

@@ -202,6 +202,32 @@ export const REGISTRY = [
             {key: 'update', label: 'Dismiss', description: 'Mark notifications as read'},
             {key: 'delete', label: 'Clear', description: 'Delete notifications'}
         ]
+    },
+    {
+        key: 'api-tokens',
+        label: 'API Tokens',
+        description: 'Manage project-scoped tokens for the external collections API.',
+        icon: 'key',
+        group: 'Configuration',
+        actions: [
+            {key: 'read',   label: 'View',   description: 'View API tokens (hashes are never shown)'},
+            {key: 'create', label: 'Create', description: 'Create new API tokens'},
+            {key: 'update', label: 'Edit',   description: 'Rename, enable/disable, or edit token scopes'},
+            {key: 'delete', label: 'Revoke', description: 'Revoke (delete) API tokens'}
+        ]
+    },
+    {
+        key: 'api-endpoints',
+        label: 'API Builder',
+        description: 'Build custom REST endpoints over collection data (/api/x/*).',
+        icon: 'code',
+        group: 'Configuration',
+        actions: [
+            {key: 'read',   label: 'View',   description: 'View custom API endpoint definitions'},
+            {key: 'create', label: 'Create', description: 'Create new endpoint definitions'},
+            {key: 'update', label: 'Edit',   description: 'Edit endpoint definitions'},
+            {key: 'delete', label: 'Delete', description: 'Delete endpoint definitions'}
+        ]
     }
 ];
 

package/server/services/presetCollections.js

@@ -60,6 +60,60 @@ const PRESETS = [
             delete: {enabled: false, access: 'admin'}
         }
     }
+    ,
+    {
+        slug: 'api-tokens',
+        title: 'API Tokens',
+        description: 'Project-scoped tokens for the external collections API.',
+        preset: true,
+        systemManaged: true,
+        fields: [
+            {name: 'name',       label: 'Name',        type: 'text',     required: true},
+            {name: 'project',    label: 'Project',     type: 'text',     required: true},
+            {name: 'tokenHash',  label: 'Token Hash',  type: 'hidden',   required: true},
+            {name: 'tokenHint',  label: 'Hint',        type: 'text'},
+            {name: 'scopes',     label: 'Scopes',      type: 'array',    items: 'object', default: []},
+            {name: 'enabled',    label: 'Enabled',     type: 'boolean',  default: true},
+            {name: 'expiresAt',  label: 'Expires At',  type: 'datetime'},
+            {name: 'lastUsedAt', label: 'Last Used',   type: 'datetime'},
+            {name: 'createdBy',  label: 'Created By',  type: 'text'}
+        ],
+        api: {
+            create: {enabled: false, access: 'admin'},
+            read:   {enabled: false, access: 'admin'},
+            update: {enabled: false, access: 'admin'},
+            delete: {enabled: false, access: 'admin'}
+        }
+    }
+    ,
+    {
+        slug: 'api-endpoints',
+        title: 'API Endpoints',
+        description: 'Curated custom REST endpoints over collection data (/api/x/*).',
+        preset: true,
+        systemManaged: true,
+        fields: [
+            {name: 'name',       label: 'Name',        type: 'text',     required: true},
+            {name: 'project',    label: 'Project',     type: 'text',     required: true},
+            {name: 'path',       label: 'Path',        type: 'text',     required: true},
+            {name: 'collection', label: 'Collection',  type: 'text',     required: true},
+            {name: 'auth',       label: 'Auth',        type: 'text',     default: 'public'},
+            {name: 'mode',       label: 'Mode',        type: 'select',   options: ['list', 'single'], default: 'list'},
+            {name: 'filter',     label: 'Filter',      type: 'object',   default: {}},
+            {name: 'sort',       label: 'Sort Field',  type: 'text'},
+            {name: 'order',      label: 'Sort Order',  type: 'select',   options: ['asc', 'desc'], default: 'desc'},
+            {name: 'limit',      label: 'Limit',       type: 'number',   default: 50},
+            {name: 'fields',     label: 'Fields',      type: 'array',    items: 'string', default: []},
+            {name: 'enabled',    label: 'Enabled',     type: 'boolean',  default: true},
+            {name: 'createdBy',  label: 'Created By',  type: 'text'}
+        ],
+        api: {
+            create: {enabled: false, access: 'admin'},
+            read:   {enabled: false, access: 'admin'},
+            update: {enabled: false, access: 'admin'},
+            delete: {enabled: false, access: 'admin'}
+        }
+    }
 ];
 
 /** Slugs exported for use in adapterRegistry and the delete guard. */

package/server/services/projects.js

@@ -337,7 +337,7 @@ export async function getProjectForPage(urlPath, explicitProject) {
 export async function getArtefactsForProject(projectSlug) {
     const out = {
         pages: [], collections: [], forms: [], actions: [],
-        menus: [], blocks: [], views: [], roles: [], users: []
+        menus: [], blocks: [], views: [], roles: [], users: [], apis: []
     };
 
     try {
@@ -411,6 +411,17 @@ export async function getArtefactsForProject(projectSlug) {
         }
     } catch { /* skip */ }
 
+    try {
+        // Custom API endpoints store their project in data.project (required
+        // field — no untagged-→core fallback applies, so match directly).
+        const {entries} = await listEntries('api-endpoints', {limit: 0});
+        for (const e of entries) {
+            if (e.data?.project === projectSlug) {
+                out.apis.push({id: e.id, name: e.data.name, path: e.data.path, collection: e.data.collection});
+            }
+        }
+    } catch { /* skip */ }
+
     return out;
 }
 
@@ -436,7 +447,7 @@ export async function untagAllForProject(projectSlug) {
     }
     const counts = {
         pages: 0, collections: 0, forms: 0, actions: 0,
-        menus: 0, blocks: 0, views: 0, roles: 0, users: 0
+        menus: 0, blocks: 0, views: 0, roles: 0, users: 0, apis: 0
     };
     const grouped = await getArtefactsForProject(projectSlug);
 
@@ -516,6 +527,11 @@ export async function untagAllForProject(projectSlug) {
     // plumbing to land first; pages need frontmatter rewriting which is a
     // separate concern. Counts remain 0 for those types in this task; later
     // tasks may revisit.
+    //
+    // API endpoints: intentionally skipped. An endpoint's project IS its URL
+    // namespace (/api/x/<project>/...) — silently untagging would move live
+    // endpoints to /api/x/core/... and break external callers. Delete or
+    // recreate them explicitly instead.
 
     return counts;
 }

package/server/services/roles.js

@@ -198,6 +198,22 @@ export async function seed() {
         await writeData(entries);
     }
 
+    // Self-heal: ensure the level-0 root role always carries every registry
+    // resource. Role permissions are a persisted snapshot taken at seed time,
+    // so new permission families added in an update (e.g. api-tokens) would
+    // otherwise be invisible — even to the super-admin — on existing installs.
+    // Other roles are intentionally NOT back-filled; admins grant new
+    // families via the role editor.
+    const root = entries.find(e => e.data?.level === 0);
+    if (root) {
+        const perms = root.data.permissions || [];
+        const missing = RESOURCES.filter(r => !perms.some(p => p === r || p.startsWith(`${r}.`)));
+        if (missing.length) {
+            root.data.permissions = [...perms, ...missing];
+            await writeData(entries);
+        }
+    }
+
     // Migrate existing user files whose role is no longer recognised
     await migrateUserRoles(entries);
 }

package/server/services/scaffolder.js

@@ -279,7 +279,7 @@ export async function applyRecipe(recipeSlug, opts = {}) {
         throw err;
     }
 
-    const created  = { collection: null, form: null, actions: [], roles: [], users: [], menus: [] };
+    const created  = { collection: null, form: null, actions: [], roles: [], users: [], menus: [], apiTokens: [], apiEndpoints: [] };
     const skipped  = [];
     const warnings = [];
 
@@ -459,6 +459,59 @@ export async function applyRecipe(recipeSlug, opts = {}) {
         } catch { /* non-fatal — admin can wire it manually */ }
     }
 
+    // API tokens — generated at apply time; the plaintext rides ONCE in
+    // `created.apiTokens[].token` (only a hash is stored). Idempotent:
+    // re-applying never re-issues an existing name+project token, so the
+    // credential the user already deployed survives recipe re-runs.
+    const tokenDecls = resolved.apiTokens ? [].concat(resolved.apiTokens) : [];
+    if (tokenDecls.length) {
+        const {createToken, findTokenByName} = await import('./apiTokens.js');
+        const tokenProject = projectSlug || tokens.namespace || 'core';
+        for (const t of tokenDecls) {
+            if (!t.name) continue;
+            if (await findTokenByName(t.name, tokenProject)) {
+                skipped.push(`apiToken:${t.name}`);
+                warnings.push(`API token "${t.name}" already exists for project "${tokenProject}" — left unchanged (token value NOT re-issued)`);
+                continue;
+            }
+            try {
+                const {plaintext} = await createToken({
+                    name:      t.name,
+                    project:   tokenProject,
+                    scopes:    Array.isArray(t.scopes) ? t.scopes : [],
+                    expiresAt: t.expiresAt || null,
+                    createdBy: opts.createdBy || null
+                });
+                created.apiTokens.push({name: t.name, token: plaintext});
+            } catch (err) {
+                warnings.push(`API token "${t.name}" failed: ${err.message}`);
+            }
+        }
+    }
+
+    // Custom API endpoints — declared as definition objects (path, collection,
+    // filter, ...). Idempotent: an existing (project, path-shape) match is
+    // skipped so re-applying a recipe never clobbers a tuned definition.
+    const endpointDecls = resolved.apiEndpoints ? [].concat(resolved.apiEndpoints) : [];
+    if (endpointDecls.length) {
+        const {createEndpoint, findEndpointByPath} = await import('./apiEndpoints.js');
+        const epProject = projectSlug || tokens.namespace || 'core';
+        for (const ep of endpointDecls) {
+            if (!ep.path) continue;
+            if (await findEndpointByPath(epProject, ep.path)) {
+                skipped.push(`apiEndpoint:${ep.path}`);
+                warnings.push(`API endpoint "${ep.path}" already exists for project "${epProject}" — left unchanged`);
+                continue;
+            }
+            try {
+                await createEndpoint({...ep, project: epProject, createdBy: opts.createdBy || null});
+                created.apiEndpoints.push(ep.path);
+            } catch (err) {
+                warnings.push(`API endpoint "${ep.path}" failed: ${err.message}`);
+            }
+        }
+    }
+
     const snippet = resolved.snippet || null;
 
     return { created, skipped, warnings, snippet };

package/server/services/sidebar-migration.js

@@ -41,6 +41,7 @@ const SEED_ITEMS = [
             {text: 'Forms',       url: '#/forms',       icon: 'layout',    permission: 'collections'},
             {text: 'Views',       url: '#/views',       icon: 'eye',       permission: 'views'},
             {text: 'Actions',     url: '#/actions',     icon: 'zap',       permission: 'actions'},
+            {text: 'API Builder', url: '#/api-endpoints', icon: 'code',    permission: 'api-endpoints'},
             {text: 'Blocks',      url: '#/blocks',      icon: 'box',       permission: 'pages'},
             {text: 'Components',  url: '#/components',  icon: 'component', permission: 'components'}
         ]
@@ -55,6 +56,7 @@ const SEED_ITEMS = [
             {text: 'Effects',       url: '#/effects',              icon: 'sparkles', permission: 'settings'},
             {text: 'Layouts',       url: '#/layouts',              icon: 'layout',   permission: 'layouts'},
             {text: 'Plugins',       url: '#/plugins',              icon: 'package',  permission: 'plugins'},
+            {text: 'API Tokens',    url: '#/api-tokens',           icon: 'key',      permission: 'api-tokens'},
             {text: 'My Profile',    url: '#/my-profile',           icon: 'user'}
         ]
     },
@@ -115,3 +117,46 @@ export async function runMigration(opts = {}) {
     console.log('[admin-sidebar] Seeded admin-sidebar menu + mapped admin-sidebar slot');
     return {migrated: true};
 }
+
+/**
+ * Append-if-absent: ensure a single item exists in the persisted admin
+ * sidebar menu. Lets updates surface new admin pages on EXISTING installs
+ * (the seed above only reaches fresh ones) without clobbering admin edits:
+ * if any node in the tree already has the item's url — even moved, renamed,
+ * or hidden — this is a no-op.
+ *
+ * Returns `{ensured: boolean, reason?: string}`.
+ *
+ * @param {{groupText: string, item: {text: string, url: string, icon?: string, permission?: string}}} spec
+ * @param {{configDir?: string}} [opts]
+ */
+export async function ensureSidebarItem({groupText, item}, opts = {}) {
+    const configDir = opts.configDir || DEFAULT_CONFIG_DIR;
+    const menuPath  = path.join(configDir, 'menus', 'admin-sidebar.json');
+
+    if (!await exists(menuPath)) {
+        return {ensured: false, reason: 'admin-sidebar.json not present'};
+    }
+
+    const menu = await readJson(menuPath);
+    const items = Array.isArray(menu.items) ? menu.items : (menu.items = []);
+
+    const hasUrl = (nodes) => nodes.some(n => n?.url === item.url || (Array.isArray(n?.items) && hasUrl(n.items)));
+    if (hasUrl(items)) {
+        return {ensured: false, reason: 'item already present'};
+    }
+
+    let group = items.find(n => typeof n?.text === 'string' && n.text.toLowerCase() === groupText.toLowerCase());
+    if (!group) {
+        group = {text: groupText, items: []};
+        items.push(group);
+    }
+    if (!Array.isArray(group.items)) group.items = [];
+    group.items.push(item);
+
+    menu.meta = {...(menu.meta || {}), updatedAt: new Date().toISOString()};
+    await writeJson(menuPath, menu);
+
+    console.log(`[admin-sidebar] Added "${item.text}" to the ${groupText} group`);
+    return {ensured: true};
+}