domma-cms 0.23.0 → 0.25.0

package/server/routes/api/collections.js

@@ -22,6 +22,20 @@
  * POST   /collections/:slug/public       - Create entry (if api.create enabled)
  * PUT    /collections/:slug/public/:id   - Update entry (if api.update enabled)
  * DELETE /collections/:slug/public/:id   - Delete entry (if api.delete enabled)
+ *
+ * External versioned alias (same handlers, stable URL for API consumers):
+ * GET    /v1/:slug          ≡ GET    /collections/:slug/public
+ * GET    /v1/:slug/:id      ≡ GET    /collections/:slug/public/:id
+ * POST   /v1/:slug          ≡ POST   /collections/:slug/public
+ * PUT    /v1/:slug/:id      ≡ PUT    /collections/:slug/public/:id
+ * DELETE /v1/:slug/:id      ≡ DELETE /collections/:slug/public/:id
+ *
+ * Access modes per verb (`schema.api.<verb>.access`): 'public', a role name
+ * (JWT + role level), or 'token' (project-scoped API token — see
+ * services/apiTokens.js). A token is ONLY accepted when the mode is 'token';
+ * it is never a substitute for a role, and a JWT is never accepted in token
+ * mode. `schema.api.read.fields` optionally whitelists which data fields the
+ * public/external read endpoints return.
  */
 import {
     clearEntries,
@@ -45,6 +59,8 @@ import {getConfig, saveConfig} from '../../config.js';
 import {PRESET_COLLECTION_SLUGS} from '../../services/presetCollections.js';
 import {ensureFormForCollection} from '../../services/forms.js';
 import {hooks} from '../../services/hooks.js';
+import {scopeAllows, validateToken} from '../../services/apiTokens.js';
+import {resolveArtefactProject} from '../../services/projects.js';
 
 const ALL_PRESET_SLUGS = new Set(['roles', 'user-profiles', ...PRESET_COLLECTION_SLUGS]);
 
@@ -82,6 +98,43 @@ function extractBracketed(query, prefix) {
     return out;
 }
 
+/**
+ * Redact the stored token hash from an api-tokens entry. The generic admin
+ * entry endpoints would otherwise expose it to anyone with collections.read.
+ * (SHA-256 of 32 random bytes is not reversible, but there is no reason to
+ * show it.) Token management belongs to /api/api-tokens.
+ *
+ * @param {object} entry
+ * @returns {object}
+ */
+function redactTokenHash(entry) {
+    if (!entry?.data || entry.data.tokenHash === undefined) return entry;
+    const { tokenHash, ...data } = entry.data;
+    return { ...entry, data };
+}
+
+/**
+ * Apply the read-field allowlist (`schema.api.read.fields`) to a public read
+ * payload. Absent or empty allowlist = all fields. Handles both list payloads
+ * ({entries: [...]}) and single entries. Only entry.data is filtered —
+ * `_refs` from resolveRefs is not (refs of stripped fields may still appear;
+ * documented v1 behaviour).
+ *
+ * @param {object} schema
+ * @param {object} payload - listEntries() result or a single entry
+ * @returns {object}
+ */
+export function applyReadFieldAllowlist(schema, payload) {
+    const fields = schema.api?.read?.fields;
+    if (!Array.isArray(fields) || fields.length === 0) return payload;
+    const strip = (e) => ({
+        ...e,
+        data: Object.fromEntries(Object.entries(e.data || {}).filter(([k]) => fields.includes(k)))
+    });
+    if (Array.isArray(payload?.entries)) return { ...payload, entries: payload.entries.map(strip) };
+    return strip(payload);
+}
+
 /**
  * Check public collection API access.
  * Returns an error reply if access is denied, otherwise resolves (returns undefined).
@@ -92,7 +145,7 @@ function extractBracketed(query, prefix) {
  * @param {object} reply   - Fastify reply
  * @returns {Promise<object|undefined>}
  */
-async function checkPublicAccess(schema, operation, request, reply) {
+export async function checkPublicAccess(schema, operation, request, reply) {
     const access = schema.api?.[operation];
     if (!access?.enabled) {
         return reply.status(403).send({ error: `Public ${operation} is disabled for this collection` });
@@ -100,6 +153,28 @@ async function checkPublicAccess(schema, operation, request, reply) {
 
     if (access.access === 'public') return; // No auth needed
 
+    // Token mode — project-scoped API token, strict: a token is the ONLY
+    // accepted credential here (a JWT never satisfies token mode, and a
+    // token never satisfies a role mode).
+    if (access.access === 'token') {
+        const match = (request.headers.authorization || '').match(/^Bearer (dcms_[a-f0-9]{64})$/);
+        if (!match) {
+            return reply.status(401).send({ error: 'API token required' });
+        }
+        const token = await validateToken(match[1]);
+        if (!token) {
+            return reply.status(401).send({ error: 'Invalid, disabled or expired API token' });
+        }
+        if (token.project !== resolveArtefactProject(schema)) {
+            return reply.status(403).send({ error: "Token is not valid for this collection's project" });
+        }
+        if (!scopeAllows(token.scopes, schema.slug, operation)) {
+            return reply.status(403).send({ error: 'Token scope does not permit this operation' });
+        }
+        request.apiToken = token;
+        return;
+    }
+
     // Auth required — try to verify JWT
     try {
         await request.jwtVerify();
@@ -240,7 +315,7 @@ export async function collectionsRoutes(fastify) {
         if (!schema) return reply.status(404).send({ error: 'Collection not found' });
         const { page, limit, sort, order, search } = request.query;
         const filter = extractBracketed(request.query, 'filter');
-        return listEntries(request.params.slug, {
+        const result = await listEntries(request.params.slug, {
             page:   parseInt(page, 10)  || 1,
             limit:  parseInt(limit, 10) || 50,
             sort:   sort   || 'createdAt',
@@ -248,12 +323,16 @@ export async function collectionsRoutes(fastify) {
             search: search || undefined,
             filter: Object.keys(filter).length ? filter : undefined
         });
+        if (request.params.slug === 'api-tokens') {
+            result.entries = result.entries.map(redactTokenHash);
+        }
+        return result;
     });
 
     fastify.get('/collections/:slug/entries/:id', canRead, async (request, reply) => {
         const entry = await getEntry(request.params.slug, request.params.id);
         if (!entry) return reply.status(404).send({ error: 'Entry not found' });
-        return entry;
+        return request.params.slug === 'api-tokens' ? redactTokenHash(entry) : entry;
     });
 
     fastify.post('/collections/:slug/entries', canCreate, async (request, reply) => {
@@ -415,7 +494,7 @@ export async function collectionsRoutes(fastify) {
      *                  `[collection scope="mine"]` shortcode for per-user
      *                  client-side hydration (e.g. "My Applications").
      */
-    fastify.get('/collections/:slug/public', async (request, reply) => {
+    async function publicListEntries(request, reply) {
         const schema = await getCollection(request.params.slug);
         if (!schema) return reply.status(404).send({ error: 'Collection not found' });
 
@@ -442,7 +521,7 @@ export async function collectionsRoutes(fastify) {
             if (denied !== undefined) return;
         }
 
-        return listEntries(request.params.slug, {
+        const result = await listEntries(request.params.slug, {
             page:   parseInt(page, 10)  || 1,
             limit:  parseInt(limit, 10) || 50,
             sort:   sort   || 'createdAt',
@@ -451,9 +530,10 @@ export async function collectionsRoutes(fastify) {
             filter: Object.keys(filter).length ? filter : undefined,
             resolveRefs: resolveRefs === 'true' || resolveRefs === '1'
         });
-    });
+        return applyReadFieldAllowlist(schema, result);
+    }
 
-    fastify.get('/collections/:slug/public/:id', async (request, reply) => {
+    async function publicGetEntry(request, reply) {
         const schema = await getCollection(request.params.slug);
         if (!schema) return reply.status(404).send({ error: 'Collection not found' });
 
@@ -462,8 +542,11 @@ export async function collectionsRoutes(fastify) {
 
         const entry = await getEntry(request.params.slug, request.params.id);
         if (!entry) return reply.status(404).send({ error: 'Entry not found' });
-        return entry;
-    });
+        return applyReadFieldAllowlist(schema, entry);
+    }
+
+    fastify.get('/collections/:slug/public', publicListEntries);
+    fastify.get('/collections/:slug/public/:id', publicGetEntry);
 
     /*
      * POST /api/collections/render-scope
@@ -567,7 +650,7 @@ export async function collectionsRoutes(fastify) {
         return { html };
     });
 
-    fastify.post('/collections/:slug/public', async (request, reply) => {
+    async function publicCreateEntry(request, reply) {
         const schema = await getCollection(request.params.slug);
         if (!schema) return reply.status(404).send({ error: 'Collection not found' });
 
@@ -575,18 +658,17 @@ export async function collectionsRoutes(fastify) {
         if (denied !== undefined) return;
 
         try {
-            const user  = request.user;
             const entry = await createEntry(request.params.slug, request.body?.data || {}, {
-                createdBy: user?.id || null,
+                createdBy: request.apiToken ? `token:${request.apiToken.id}` : (request.user?.id || null),
                 source:    'api'
             });
             return reply.status(201).send(entry);
         } catch (err) {
             return reply.status(400).send({ error: err.message });
         }
-    });
+    }
 
-    fastify.put('/collections/:slug/public/:id', async (request, reply) => {
+    async function publicUpdateEntry(request, reply) {
         const schema = await getCollection(request.params.slug);
         if (!schema) return reply.status(404).send({ error: 'Collection not found' });
 
@@ -599,9 +681,9 @@ export async function collectionsRoutes(fastify) {
             const status = err.message === 'Entry not found' ? 404 : 400;
             return reply.status(status).send({ error: err.message });
         }
-    });
+    }
 
-    fastify.delete('/collections/:slug/public/:id', async (request, reply) => {
+    async function publicDeleteEntry(request, reply) {
         const schema = await getCollection(request.params.slug);
         if (!schema) return reply.status(404).send({ error: 'Collection not found' });
 
@@ -614,5 +696,20 @@ export async function collectionsRoutes(fastify) {
         } catch (err) {
             return reply.status(404).send({ error: err.message });
         }
-    });
+    }
+
+    fastify.post('/collections/:slug/public', publicCreateEntry);
+    fastify.put('/collections/:slug/public/:id', publicUpdateEntry);
+    fastify.delete('/collections/:slug/public/:id', publicDeleteEntry);
+
+    // -------------------------------------------------------------------------
+    // External versioned API — stable alias of the public endpoints above.
+    // Documented surface for external consumers (docs/api-reference.md).
+    // -------------------------------------------------------------------------
+
+    fastify.get('/v1/:slug', publicListEntries);
+    fastify.get('/v1/:slug/:id', publicGetEntry);
+    fastify.post('/v1/:slug', publicCreateEntry);
+    fastify.put('/v1/:slug/:id', publicUpdateEntry);
+    fastify.delete('/v1/:slug/:id', publicDeleteEntry);
 }

package/server/routes/api/endpoints-public.js

@@ -0,0 +1,88 @@
+/**
+ * Custom API Endpoints — public surface
+ *
+ * One catch-all serves every user-defined endpoint:
+ *   GET /api/x/<project><path>     e.g. /api/x/world-cup/fixtures-day/2026-06-11
+ *
+ * Definitions live in the `api-endpoints` preset collection and are matched
+ * at request time by services/apiEndpoints.js. Auth (public / token / role),
+ * project binding, token scopes, and the read field allowlist all reuse the
+ * public collections machinery via a synthesized schema — one battle-tested
+ * code path for every external read.
+ *
+ * Unknown project, unknown path, and disabled endpoints all 404 identically
+ * (no existence oracle). GET-only in v1.
+ */
+import {EndpointParamError, executeEndpoint, matchEndpoint} from '../../services/apiEndpoints.js';
+import {applyReadFieldAllowlist, checkPublicAccess} from './collections.js';
+import * as cache from '../../services/cache/index.js';
+
+/** Cached sentinel for single-mode misses — a miss is a cacheable answer. */
+const NOT_FOUND = {__endpointNotFound: true};
+
+/**
+ * Stable query-string representation for cache keys.
+ *
+ * @param {Record<string, string>} query
+ * @returns {string}
+ */
+function sortedQueryString(query) {
+    return Object.keys(query || {})
+        .sort()
+        .map(k => `${k}=${query[k]}`)
+        .join('&');
+}
+
+export async function endpointsPublicRoutes(fastify) {
+    fastify.get('/x/*', async (request, reply) => {
+        const segments = String(request.params['*'] || '').split('/').filter(Boolean);
+        if (segments.length < 2) return reply.status(404).send({ error: 'Not found' });
+
+        const [project, ...rest] = segments;
+        const match = await matchEndpoint(project, rest);
+        if (!match) return reply.status(404).send({ error: 'Not found' });
+
+        const {def, params} = match;
+
+        // Synthesized schema — checkPublicAccess reads exactly api.read,
+        // slug (token scopes), and meta.project (token project binding).
+        const synth = {
+            slug: def.collection,
+            api: { read: { enabled: true, access: def.auth, fields: def.fields } },
+            meta: { project: def.project }
+        };
+        const denied = await checkPublicAccess(synth, 'read', request, reply);
+        if (denied !== undefined) return;
+
+        const run = async () => {
+            const result = await executeEndpoint(def, params, request.query);
+            if (def.mode === 'single') {
+                return result === null ? NOT_FOUND : applyReadFieldAllowlist(synth, result);
+            }
+            return applyReadFieldAllowlist(synth, result);
+        };
+
+        try {
+            // Only public responses are cacheable — token/role responses are
+            // caller-dependent. Both tags are invalidated by the service layer
+            // on every write path: entry mutations bust collection:<slug>, and
+            // definition edits (entries in api-endpoints) bust
+            // collection:api-endpoints. No manual invalidation needed.
+            const payload = def.auth === 'public'
+                ? await cache.wrap(
+                    `apix:${project}:${rest.join('/')}:${sortedQueryString(request.query)}`,
+                    run,
+                    { tags: [`collection:${def.collection}`, 'collection:api-endpoints'] }
+                )
+                : await run();
+
+            if (payload?.__endpointNotFound) return reply.status(404).send({ error: 'Not found' });
+            return payload;
+        } catch (err) {
+            if (err instanceof EndpointParamError) {
+                return reply.status(400).send({ error: err.message });
+            }
+            throw err;
+        }
+    });
+}

package/server/routes/api/navigation.js

@@ -1,42 +1,42 @@
-/**
- * Navigation API
- * GET /api/navigation    - get navigation config
- * PUT /api/navigation    - save navigation config
- */
-import {getConfig, saveConfig} from '../../config.js';
-import {authenticate, requirePermission} from '../../middleware/auth.js';
-import * as cache from '../../services/cache/index.js';
-
-export async function navigationRoutes(fastify) {
-    const canRead = {preHandler: [authenticate, requirePermission('navigation', 'read')]};
-    const canUpdate = {preHandler: [authenticate, requirePermission('navigation', 'update')]};
-
-    fastify.get('/navigation', canRead, async () => {
-        return getConfig('navigation');
-    });
-
-    fastify.put('/navigation', canUpdate, async (request, reply) => {
-        const data = request.body;
-        if (!data || typeof data !== 'object') {
-            return reply.status(400).send({ error: 'Invalid navigation data' });
-        }
-        if (!Array.isArray(data.items) && !Array.isArray(data)) {
-            return reply.status(400).send({ error: 'Navigation must be an array of items' });
-        }
-        // Normalise child key: Domma navbar expects `items`, not `children`
-        if (Array.isArray(data.items)) {
-            data.items = data.items.map(item => {
-                const children = item.items || item.children;
-                if (children?.length) {
-                    const { children: _c, ...rest } = item;
-                    return { ...rest, items: children };
-                }
-                const { children: _c, ...rest } = item;
-                return rest;
-            });
-        }
-        saveConfig('navigation', data);
-        await cache.invalidateTags(['nav']);
-        return { success: true };
-    });
-}
+/**
+ * Navigation API
+ * GET /api/navigation    - get navigation config
+ * PUT /api/navigation    - save navigation config
+ */
+import {getConfig, saveConfig} from '../../config.js';
+import {authenticate, requirePermission} from '../../middleware/auth.js';
+import * as cache from '../../services/cache/index.js';
+
+export async function navigationRoutes(fastify) {
+    const canRead = {preHandler: [authenticate, requirePermission('navigation', 'read')]};
+    const canUpdate = {preHandler: [authenticate, requirePermission('navigation', 'update')]};
+
+    fastify.get('/navigation', canRead, async () => {
+        return getConfig('navigation');
+    });
+
+    fastify.put('/navigation', canUpdate, async (request, reply) => {
+        const data = request.body;
+        if (!data || typeof data !== 'object') {
+            return reply.status(400).send({ error: 'Invalid navigation data' });
+        }
+        if (!Array.isArray(data.items) && !Array.isArray(data)) {
+            return reply.status(400).send({ error: 'Navigation must be an array of items' });
+        }
+        // Normalise child key: Domma navbar expects `items`, not `children`
+        if (Array.isArray(data.items)) {
+            data.items = data.items.map(item => {
+                const children = item.items || item.children;
+                if (children?.length) {
+                    const { children: _c, ...rest } = item;
+                    return { ...rest, items: children };
+                }
+                const { children: _c, ...rest } = item;
+                return rest;
+            });
+        }
+        saveConfig('navigation', data);
+        await cache.invalidateTags(['nav']);
+        return { success: true };
+    });
+}