domma-cms 0.23.0 → 0.24.0

package/server/services/apiTokens.js

@@ -0,0 +1,259 @@
+/**
+ * API Tokens
+ * Project-scoped machine credentials for the external collections API.
+ *
+ * Tokens are entries in the file-based `api-tokens` preset collection.
+ * Only a SHA-256 hash is stored — the plaintext (`dcms_<64 hex>`) is returned
+ * exactly once, from createToken(). A token is accepted only on collection
+ * verbs configured with `api.<verb>.access === 'token'`, and only for
+ * collections whose resolved project matches the token's `project` binding.
+ */
+import crypto from 'node:crypto';
+import {createEntry, deleteEntry, getEntry, listEntries, updateEntry} from './collections.js';
+import {canSeeArtefact, getProject} from './projects.js';
+import {hooks} from './hooks.js';
+
+export const API_TOKENS_COLLECTION_SLUG = 'api-tokens';
+
+const TOKEN_RE = /^dcms_[a-f0-9]{64}$/;
+const VERBS = ['create', 'read', 'update', 'delete'];
+const LAST_USED_THROTTLE_MS = 60_000;
+
+/** In-memory hash → entry cache; null = needs rebuild. */
+let tokenCache = null;
+
+function invalidateCache() {
+    tokenCache = null;
+}
+
+// Generic admin collection endpoints emit these for ALL collections — the
+// service's own mutations invalidate directly, this catches edits made
+// through the admin entries grid.
+for (const ev of ['collection:entryCreated', 'collection:entryUpdated', 'collection:entryDeleted']) {
+    hooks.on(ev, (payload) => {
+        if (payload?.slug === API_TOKENS_COLLECTION_SLUG) invalidateCache();
+    });
+}
+
+/**
+ * SHA-256 hex digest of a plaintext token.
+ *
+ * @param {string} plaintext
+ * @returns {string}
+ */
+function hashToken(plaintext) {
+    return crypto.createHash('sha256').update(plaintext).digest('hex');
+}
+
+/**
+ * Strip the entry down to what callers may see. Never includes tokenHash.
+ *
+ * @param {object} entry - Raw collection entry { id, data, meta }
+ * @returns {object}
+ */
+function sanitise(entry) {
+    const {name, project, tokenHint, scopes, enabled, expiresAt, lastUsedAt, createdBy} = entry.data || {};
+    return {
+        id: entry.id,
+        name, project, tokenHint,
+        scopes: Array.isArray(scopes) ? scopes : [],
+        enabled: enabled !== false,
+        expiresAt: expiresAt || null,
+        lastUsedAt: lastUsedAt || null,
+        createdBy: createdBy || null,
+        meta: entry.meta
+    };
+}
+
+/**
+ * Validate a scopes declaration: array of { collection, verbs[] }.
+ * Empty array = the token covers every collection in its project.
+ *
+ * @param {*} scopes
+ * @returns {string|null} Error message, or null when valid
+ */
+function validateScopes(scopes) {
+    if (scopes == null) return null;
+    if (!Array.isArray(scopes)) return 'scopes must be an array';
+    for (const s of scopes) {
+        if (!s || typeof s !== 'object' || typeof s.collection !== 'string' || !s.collection.trim()) {
+            return 'each scope needs a collection slug';
+        }
+        if (s.verbs != null) {
+            if (!Array.isArray(s.verbs)) return 'scope verbs must be an array';
+            const bad = s.verbs.find(v => !VERBS.includes(v));
+            if (bad) return `unknown scope verb "${bad}"`;
+        }
+    }
+    return null;
+}
+
+/**
+ * Check whether a token's scopes permit an operation on a collection.
+ * Empty/missing scopes → everything in the token's project is allowed.
+ *
+ * @param {Array<{collection: string, verbs?: string[]}>} scopes
+ * @param {string} collectionSlug
+ * @param {string} verb - create | read | update | delete
+ * @returns {boolean}
+ */
+export function scopeAllows(scopes, collectionSlug, verb) {
+    if (!Array.isArray(scopes) || scopes.length === 0) return true;
+    const scope = scopes.find(s => s.collection === collectionSlug);
+    if (!scope) return false;
+    return !Array.isArray(scope.verbs) || scope.verbs.length === 0 || scope.verbs.includes(verb);
+}
+
+/**
+ * Create a new token. The plaintext is returned ONCE here and never again.
+ *
+ * @param {{name: string, project: string, scopes?: object[], expiresAt?: string|null, createdBy?: string|null}} input
+ * @returns {Promise<{entry: object, plaintext: string}>} Sanitised entry + plaintext
+ * @throws {Error} On validation failure
+ */
+export async function createToken({name, project, scopes = [], expiresAt = null, createdBy = null}) {
+    if (!name || typeof name !== 'string' || !name.trim()) throw new Error('Token name is required');
+    if (!project || typeof project !== 'string') throw new Error('Token project is required');
+    if (!await getProject(project)) throw new Error(`Unknown project "${project}"`);
+    const scopeError = validateScopes(scopes);
+    if (scopeError) throw new Error(scopeError);
+    if (expiresAt != null && Number.isNaN(Date.parse(expiresAt))) throw new Error('expiresAt must be a valid date');
+
+    const plaintext = 'dcms_' + crypto.randomBytes(32).toString('hex');
+    const data = {
+        name: name.trim(),
+        project,
+        tokenHash: hashToken(plaintext),
+        tokenHint: plaintext.slice(-4),
+        scopes: scopes || [],
+        enabled: true,
+        expiresAt: expiresAt || null,
+        lastUsedAt: null,
+        createdBy
+    };
+
+    const entry = await createEntry(API_TOKENS_COLLECTION_SLUG, data, {createdBy, source: 'admin'});
+    invalidateCache();
+    return {entry: sanitise(entry), plaintext};
+}
+
+/**
+ * Look up a token by name + project. Used for scaffolder idempotency.
+ *
+ * @param {string} name
+ * @param {string} project
+ * @returns {Promise<object|null>} Sanitised entry or null
+ */
+export async function findTokenByName(name, project) {
+    const {entries} = await listEntries(API_TOKENS_COLLECTION_SLUG, {limit: 0});
+    const entry = entries.find(e => e.data?.name === name && e.data?.project === project);
+    return entry ? sanitise(entry) : null;
+}
+
+/**
+ * Validate a presented plaintext token.
+ * Returns the sanitised entry when the token exists, is enabled, and has not
+ * expired — otherwise null. Updates lastUsedAt at most once per minute
+ * (fire-and-forget; the cached copy is patched in place to avoid thrash).
+ *
+ * @param {string} plaintext
+ * @returns {Promise<object|null>}
+ */
+export async function validateToken(plaintext) {
+    if (typeof plaintext !== 'string' || !TOKEN_RE.test(plaintext)) return null;
+    const hash = hashToken(plaintext);
+
+    if (!tokenCache) {
+        const {entries} = await listEntries(API_TOKENS_COLLECTION_SLUG, {limit: 0});
+        tokenCache = new Map(entries.map(e => [e.data?.tokenHash, e]));
+    }
+
+    const entry = tokenCache.get(hash);
+    if (!entry) return null;
+    if (entry.data.enabled === false) return null;
+    if (entry.data.expiresAt && Date.parse(entry.data.expiresAt) < Date.now()) return null;
+
+    const lastUsed = entry.data.lastUsedAt ? Date.parse(entry.data.lastUsedAt) : 0;
+    if (Date.now() - lastUsed > LAST_USED_THROTTLE_MS) {
+        // updateEntry replaces data wholesale — pass the full object.
+        const data = {...entry.data, lastUsedAt: new Date().toISOString()};
+        entry.data = data; // keep the cached copy current without invalidating
+        updateEntry(API_TOKENS_COLLECTION_SLUG, entry.id, data).catch(() => {});
+    }
+
+    return sanitise(entry);
+}
+
+/**
+ * List tokens the given admin user may see (project access scope applies).
+ *
+ * @param {object} user
+ * @returns {Promise<object[]>} Sanitised entries
+ */
+export async function listTokensSanitised(user) {
+    const {entries} = await listEntries(API_TOKENS_COLLECTION_SLUG, {limit: 0});
+    return entries
+        .filter(e => canSeeArtefact(user, {meta: {project: e.data?.project}}))
+        .map(sanitise);
+}
+
+/**
+ * Fetch a single token, sanitised. Caller is responsible for canSeeArtefact.
+ *
+ * @param {string} id
+ * @returns {Promise<object|null>}
+ */
+export async function getTokenSanitised(id) {
+    const entry = await getEntry(API_TOKENS_COLLECTION_SLUG, id);
+    return entry ? sanitise(entry) : null;
+}
+
+/**
+ * Update mutable token fields. The project binding, hash, and hint are fixed
+ * for the token's lifetime — revoke and re-issue to rebind.
+ *
+ * @param {string} id
+ * @param {{name?: string, enabled?: boolean, scopes?: object[], expiresAt?: string|null}} patch
+ * @returns {Promise<object|null>} Sanitised entry, or null when not found
+ * @throws {Error} On validation failure
+ */
+export async function updateToken(id, patch = {}) {
+    const entry = await getEntry(API_TOKENS_COLLECTION_SLUG, id);
+    if (!entry) return null;
+
+    const data = {...entry.data};
+    if (patch.name != null) {
+        if (typeof patch.name !== 'string' || !patch.name.trim()) throw new Error('Token name is required');
+        data.name = patch.name.trim();
+    }
+    if (patch.enabled != null) data.enabled = patch.enabled !== false;
+    if (patch.scopes != null) {
+        const scopeError = validateScopes(patch.scopes);
+        if (scopeError) throw new Error(scopeError);
+        data.scopes = patch.scopes;
+    }
+    if (patch.expiresAt !== undefined) {
+        if (patch.expiresAt != null && Number.isNaN(Date.parse(patch.expiresAt))) {
+            throw new Error('expiresAt must be a valid date');
+        }
+        data.expiresAt = patch.expiresAt || null;
+    }
+
+    const updated = await updateEntry(API_TOKENS_COLLECTION_SLUG, id, data);
+    invalidateCache();
+    return updated ? sanitise(updated) : null;
+}
+
+/**
+ * Revoke (delete) a token. Takes effect immediately.
+ *
+ * @param {string} id
+ * @returns {Promise<boolean>}
+ */
+export async function revokeToken(id) {
+    const entry = await getEntry(API_TOKENS_COLLECTION_SLUG, id);
+    if (!entry) return false;
+    await deleteEntry(API_TOKENS_COLLECTION_SLUG, id);
+    invalidateCache();
+    return true;
+}

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,19 @@ 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'}
+        ]
     }
 ];
 

package/server/services/presetCollections.js

@@ -60,6 +60,31 @@ 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'}
+        }
+    }
 ];
 
 /** Slugs exported for use in adapterRegistry and the delete guard. */

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);
 }