domma-cms 0.24.0 → 0.25.1

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

@@ -0,0 +1,120 @@
+/**
+ * API Endpoints API (admin management of custom endpoint definitions)
+ *
+ * GET    /api/api-endpoints      — list definitions visible to the caller
+ * GET    /api/api-endpoints/:id  — single definition (the builder editor)
+ * POST   /api/api-endpoints      — create (400 validation, 409 duplicate path shape)
+ * PUT    /api/api-endpoints/:id  — update (project binding immutable)
+ * DELETE /api/api-endpoints/:id  — delete
+ *
+ * Endpoints are project-scoped artefacts: non-super-admin users with a
+ * `projects: []` access scope only see/manage definitions in their projects.
+ * Auth middlewares are accepted as DI options so tests can supply no-ops.
+ */
+import {
+    authenticate as defaultAuthenticate,
+    requirePermission as defaultRequirePermission
+} from '../../middleware/auth.js';
+import {
+    createEndpoint,
+    deleteEndpoint,
+    getEndpointSanitised,
+    listEndpointsSanitised,
+    updateEndpoint
+} from '../../services/apiEndpoints.js';
+import {canSeeArtefact} from '../../services/projects.js';
+import {getCollection} from '../../services/collections.js';
+
+/**
+ * Scoped users must not expose data they cannot see: the collection an
+ * endpoint queries is itself an artefact subject to project access scope.
+ * Returns true when the user may use the collection (or it doesn't exist —
+ * the service's validation produces the clearer 400 for that case).
+ *
+ * @param {object} user
+ * @param {string} slug
+ * @returns {Promise<boolean>}
+ */
+async function canUseCollection(user, slug) {
+    if (!slug) return true;
+    const schema = await getCollection(slug).catch(() => null);
+    if (!schema) return true;
+    return canSeeArtefact(user, schema);
+}
+
+/**
+ * Register the api-endpoints routes.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {{authenticate?: Function, requirePermission?: Function}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function apiEndpointsRoutes(fastify, opts = {}) {
+    const authenticate      = opts.authenticate      || defaultAuthenticate;
+    const requirePermission = opts.requirePermission || defaultRequirePermission;
+
+    const canRead   = {preHandler: [authenticate, requirePermission('api-endpoints', 'read')]};
+    const canCreate = {preHandler: [authenticate, requirePermission('api-endpoints', 'create')]};
+    const canUpdate = {preHandler: [authenticate, requirePermission('api-endpoints', 'update')]};
+    const canDelete = {preHandler: [authenticate, requirePermission('api-endpoints', 'delete')]};
+
+    const statusFor = (err) => err.code === 'DUPLICATE' ? 409 : 400;
+
+    fastify.get('/api-endpoints', canRead, async (request) => {
+        return listEndpointsSanitised(request.user);
+    });
+
+    fastify.get('/api-endpoints/:id', canRead, async (request, reply) => {
+        const def = await getEndpointSanitised(request.params.id);
+        if (!def) return reply.status(404).send({error: 'Endpoint not found'});
+        if (!canSeeArtefact(request.user, {meta: {project: def.project}})) {
+            return reply.status(403).send({error: 'Access denied for this project'});
+        }
+        return def;
+    });
+
+    fastify.post('/api-endpoints', canCreate, async (request, reply) => {
+        const input = request.body || {};
+        if (input.project && !canSeeArtefact(request.user, {meta: {project: input.project}})) {
+            return reply.status(403).send({error: 'Access denied for this project'});
+        }
+        if (!await canUseCollection(request.user, input.collection)) {
+            return reply.status(403).send({error: 'Access denied for this collection'});
+        }
+        try {
+            const creator = request.user?.name || request.user?.email || null;
+            const def = await createEndpoint({...input, createdBy: creator});
+            return reply.status(201).send(def);
+        } catch (err) {
+            return reply.status(statusFor(err)).send({error: err.message});
+        }
+    });
+
+    fastify.put('/api-endpoints/:id', canUpdate, async (request, reply) => {
+        const existing = await getEndpointSanitised(request.params.id);
+        if (!existing) return reply.status(404).send({error: 'Endpoint not found'});
+        if (!canSeeArtefact(request.user, {meta: {project: existing.project}})) {
+            return reply.status(403).send({error: 'Access denied for this project'});
+        }
+        // The project binding is the endpoint's URL namespace — immutable.
+        const {project: _ignored, ...patch} = request.body || {};
+        if (!await canUseCollection(request.user, patch.collection ?? existing.collection)) {
+            return reply.status(403).send({error: 'Access denied for this collection'});
+        }
+        try {
+            return await updateEndpoint(request.params.id, patch);
+        } catch (err) {
+            return reply.status(statusFor(err)).send({error: err.message});
+        }
+    });
+
+    fastify.delete('/api-endpoints/:id', canDelete, async (request, reply) => {
+        const existing = await getEndpointSanitised(request.params.id);
+        if (!existing) return reply.status(404).send({error: 'Endpoint not found'});
+        if (!canSeeArtefact(request.user, {meta: {project: existing.project}})) {
+            return reply.status(403).send({error: 'Access denied for this project'});
+        }
+        await deleteEndpoint(request.params.id);
+        return {success: true};
+    });
+}

package/server/routes/api/collections.js

@@ -124,7 +124,7 @@ function redactTokenHash(entry) {
  * @param {object} payload - listEntries() result or a single entry
  * @returns {object}
  */
-function applyReadFieldAllowlist(schema, payload) {
+export function applyReadFieldAllowlist(schema, payload) {
     const fields = schema.api?.read?.fields;
     if (!Array.isArray(fields) || fields.length === 0) return payload;
     const strip = (e) => ({
@@ -145,7 +145,7 @@ function applyReadFieldAllowlist(schema, payload) {
  * @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` });

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/server.js

@@ -209,6 +209,10 @@ try {
         groupText: 'System',
         item: {text: 'API Tokens', url: '#/api-tokens', icon: 'key', permission: 'api-tokens'}
     });
+    await ensureSidebarItem({
+        groupText: 'Data',
+        item: {text: 'API Builder', url: '#/api-endpoints', icon: 'code', permission: 'api-endpoints'}
+    });
 } catch (err) {
     app.log.warn(`[admin-sidebar] Migration skipped: ${err.message}`);
 }
@@ -285,6 +289,8 @@ const {menusRoutes}         = await import('./routes/api/menus.js');
 const {menuLocationsRoutes} = await import('./routes/api/menu-locations.js');
 const {projectsRoutes}      = await import('./routes/api/projects.js');
 const {apiTokensRoutes}     = await import('./routes/api/api-tokens.js');
+const {apiEndpointsRoutes}  = await import('./routes/api/api-endpoints.js');
+const {endpointsPublicRoutes} = await import('./routes/api/endpoints-public.js');
 const {sidebarRoutes}       = await import('./routes/api/sidebar.js');
 const { mediaRoutes }      = await import('./routes/api/media.js');
 const { usersRoutes }      = await import('./routes/api/users.js');
@@ -311,6 +317,8 @@ await app.register(menusRoutes,         {prefix: '/api'});
 await app.register(menuLocationsRoutes, {prefix: '/api'});
 await app.register(projectsRoutes,      {prefix: '/api'});
 await app.register(apiTokensRoutes,     {prefix: '/api'});
+await app.register(apiEndpointsRoutes,  {prefix: '/api'});
+await app.register(endpointsPublicRoutes, {prefix: '/api'});
 await app.register(sidebarRoutes,       {prefix: '/api'});
 await app.register(mediaRoutes,       { prefix: '/api' });
 await app.register(usersRoutes,       { prefix: '/api' });

package/server/services/apiEndpoints.js

@@ -0,0 +1,409 @@
+/**
+ * API Endpoints
+ * User-defined, curated REST endpoints over collection data, served at
+ * `/api/x/<project><path>` by one catch-all route.
+ *
+ * Definitions are DATA, never code: entries in the file-based `api-endpoints`
+ * preset collection. A definition binds a URL path (with `:param` segments)
+ * to a collection query — fixed filters whose values may carry
+ * `{{params.<name>}}` / `{{query.<name>}}` placeholders, sort/limit, a read
+ * field allowlist, and an auth mode (public / token / role) that reuses the
+ * exact machinery of the public collections API.
+ *
+ * Substituted values only ever feed the filterEngine — there is no eval and
+ * no way for a definition to execute code.
+ */
+import {createEntry, deleteEntry, getCollection, getEntry, listEntries, updateEntry} from './collections.js';
+import {CORE_PROJECT_SLUG, canSeeArtefact, getProject, resolveArtefactProject} from './projects.js';
+import {getRoleMap} from './roles.js';
+import {parseFilterKey} from './filterEngine.js';
+import {hooks} from './hooks.js';
+
+export const API_ENDPOINTS_COLLECTION_SLUG = 'api-endpoints';
+
+const STATIC_SEGMENT_RE = /^[a-z0-9-]+$/;
+const PARAM_SEGMENT_RE  = /^:[a-zA-Z_][a-zA-Z0-9_]*$/;
+const TEMPLATE_RE       = /\{\{\s*(params|query)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+const MODES  = ['list', 'single'];
+const ORDERS = ['asc', 'desc'];
+
+/** Thrown when a {{params.*}} placeholder cannot be resolved at request time. */
+export class EndpointParamError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EndpointParamError';
+    }
+}
+
+/** Compiled registry: Map<project, compiled[]>; null = needs rebuild. */
+let registry = null;
+
+function invalidateRegistry() {
+    registry = 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_ENDPOINTS_COLLECTION_SLUG) invalidateRegistry();
+    });
+}
+
+/**
+ * Strip an entry down to the public definition shape.
+ *
+ * @param {object} entry - Raw collection entry { id, data, meta }
+ * @returns {object}
+ */
+function sanitise(entry) {
+    const d = entry.data || {};
+    return {
+        id: entry.id,
+        name: d.name,
+        project: d.project,
+        path: d.path,
+        collection: d.collection,
+        auth: d.auth || 'public',
+        mode: MODES.includes(d.mode) ? d.mode : 'list',
+        filter: (d.filter && typeof d.filter === 'object') ? d.filter : {},
+        sort: d.sort || null,
+        order: ORDERS.includes(d.order) ? d.order : 'desc',
+        limit: Number.isInteger(d.limit) ? d.limit : 50,
+        fields: Array.isArray(d.fields) ? d.fields : [],
+        enabled: d.enabled !== false,
+        createdBy: d.createdBy || null,
+        meta: entry.meta
+    };
+}
+
+/**
+ * Normalise a path to its shape for duplicate detection — every `:param`
+ * segment collapses to `:` so `/a/:x` and `/a/:y` are the same shape.
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+function pathShape(path) {
+    return String(path).split('/').filter(Boolean)
+        .map(s => s.startsWith(':') ? ':' : s)
+        .join('/');
+}
+
+/**
+ * Validate a full endpoint definition. Throws on the first failure; the
+ * duplicate-shape error carries `code: 'DUPLICATE'` so routes can map it
+ * to 409.
+ *
+ * @param {object} data
+ * @param {{excludeId?: string}} [opts] - Skip this entry id in the duplicate check (updates)
+ * @returns {Promise<void>}
+ */
+async function validateDefinition(data, {excludeId} = {}) {
+    if (!data.name || typeof data.name !== 'string' || !data.name.trim()) {
+        throw new Error('Endpoint name is required');
+    }
+    if (!data.project || typeof data.project !== 'string') throw new Error('Endpoint project is required');
+    if (!await getProject(data.project)) throw new Error(`Unknown project "${data.project}"`);
+
+    if (!data.collection || typeof data.collection !== 'string') throw new Error('Endpoint collection is required');
+    const schema = await getCollection(data.collection);
+    if (!schema) throw new Error(`Unknown collection "${data.collection}"`);
+    if (schema.systemManaged || schema.preset) {
+        throw new Error(`Collection "${data.collection}" is system-managed and cannot be exposed`);
+    }
+    // An endpoint may only expose collections from its own project or core —
+    // the URL namespace must match where the data lives, and scoped users
+    // must not be able to publish another project's data through their own.
+    const collectionProject = resolveArtefactProject(schema);
+    if (collectionProject !== data.project && collectionProject !== CORE_PROJECT_SLUG) {
+        throw new Error(`Collection "${data.collection}" belongs to project "${collectionProject}" — an endpoint may only expose collections from its own project or core`);
+    }
+
+    if (typeof data.path !== 'string' || !data.path.startsWith('/')) {
+        throw new Error('Path must start with "/"');
+    }
+    const segments = data.path.split('/').filter(Boolean);
+    if (!segments.length) throw new Error('Path needs at least one segment');
+    const paramNames = new Set();
+    for (const seg of segments) {
+        if (PARAM_SEGMENT_RE.test(seg)) {
+            paramNames.add(seg.slice(1));
+        } else if (!STATIC_SEGMENT_RE.test(seg)) {
+            throw new Error(`Invalid path segment "${seg}" — use lowercase letters, numbers, hyphens, or :param`);
+        }
+    }
+
+    const auth = data.auth || 'public';
+    if (auth !== 'public' && auth !== 'token' && !getRoleMap().has(auth)) {
+        throw new Error(`Unknown auth mode "${auth}" — use public, token, or a role name`);
+    }
+
+    if (data.mode != null && !MODES.includes(data.mode)) throw new Error('mode must be "list" or "single"');
+    if (data.order != null && !ORDERS.includes(data.order)) throw new Error('order must be "asc" or "desc"');
+    if (data.limit != null && (!Number.isInteger(data.limit) || data.limit < 0 || data.limit > 500)) {
+        throw new Error('limit must be an integer between 0 and 500');
+    }
+    if (data.fields != null && (!Array.isArray(data.fields) || data.fields.some(f => typeof f !== 'string'))) {
+        throw new Error('fields must be an array of field names');
+    }
+
+    if (data.filter != null) {
+        if (typeof data.filter !== 'object' || Array.isArray(data.filter)) {
+            throw new Error('filter must be an object of { field_op: value }');
+        }
+        for (const [key, value] of Object.entries(data.filter)) {
+            const {field} = parseFilterKey(key);
+            if (!field) throw new Error(`Invalid filter key "${key}"`);
+            if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+                throw new Error(`Filter "${key}" must have a string, number, or boolean value`);
+            }
+            // Save-time check: every {{params.X}} must have a matching :X segment.
+            if (typeof value === 'string') {
+                for (const m of value.matchAll(TEMPLATE_RE)) {
+                    if (m[1] === 'params' && !paramNames.has(m[2])) {
+                        throw new Error(`Filter "${key}" references {{params.${m[2]}}} but the path has no :${m[2]} segment`);
+                    }
+                }
+            }
+        }
+    }
+
+    // Duplicate shape per project — `/a/:x` and `/a/:y` collide.
+    const shape = pathShape(data.path);
+    const {entries} = await listEntries(API_ENDPOINTS_COLLECTION_SLUG, {limit: 0});
+    const clash = entries.find(e =>
+        e.id !== excludeId
+        && e.data?.project === data.project
+        && pathShape(e.data?.path || '') === shape
+    );
+    if (clash) {
+        const err = new Error(`An endpoint with the path shape "${data.path}" already exists in project "${data.project}" ("${clash.data.name}")`);
+        err.code = 'DUPLICATE';
+        throw err;
+    }
+}
+
+/**
+ * Create an endpoint definition.
+ *
+ * @param {object} input
+ * @returns {Promise<object>} Sanitised definition
+ * @throws {Error} Validation failure (code 'DUPLICATE' for path clashes)
+ */
+export async function createEndpoint(input) {
+    const data = {
+        name: String(input.name || '').trim(),
+        project: input.project,
+        path: input.path,
+        collection: input.collection,
+        auth: input.auth || 'public',
+        mode: input.mode || 'list',
+        filter: input.filter || {},
+        sort: input.sort || null,
+        order: input.order || 'desc',
+        limit: input.limit ?? 50,
+        fields: input.fields || [],
+        enabled: input.enabled !== false,
+        createdBy: input.createdBy || null
+    };
+    await validateDefinition(data);
+    const entry = await createEntry(API_ENDPOINTS_COLLECTION_SLUG, data, {createdBy: data.createdBy, source: 'admin'});
+    invalidateRegistry();
+    return sanitise(entry);
+}
+
+/**
+ * Update an endpoint. The project binding is immutable (it is the endpoint's
+ * URL namespace) — create a new endpoint to move one.
+ *
+ * @param {string} id
+ * @param {object} patch
+ * @returns {Promise<object|null>}
+ */
+export async function updateEndpoint(id, patch = {}) {
+    const entry = await getEntry(API_ENDPOINTS_COLLECTION_SLUG, id);
+    if (!entry) return null;
+
+    const data = {...entry.data};
+    for (const key of ['name', 'path', 'collection', 'auth', 'mode', 'filter', 'sort', 'order', 'limit', 'fields']) {
+        if (patch[key] !== undefined) data[key] = patch[key];
+    }
+    if (patch.enabled !== undefined) data.enabled = patch.enabled !== false;
+    if (typeof data.name === 'string') data.name = data.name.trim();
+
+    await validateDefinition(data, {excludeId: id});
+    const updated = await updateEntry(API_ENDPOINTS_COLLECTION_SLUG, id, data);
+    invalidateRegistry();
+    return updated ? sanitise(updated) : null;
+}
+
+/**
+ * Delete an endpoint definition.
+ *
+ * @param {string} id
+ * @returns {Promise<boolean>}
+ */
+export async function deleteEndpoint(id) {
+    const entry = await getEntry(API_ENDPOINTS_COLLECTION_SLUG, id);
+    if (!entry) return false;
+    await deleteEntry(API_ENDPOINTS_COLLECTION_SLUG, id);
+    invalidateRegistry();
+    return true;
+}
+
+/**
+ * List endpoints visible to the given admin user (project scope applies).
+ *
+ * @param {object} user
+ * @returns {Promise<object[]>}
+ */
+export async function listEndpointsSanitised(user) {
+    const {entries} = await listEntries(API_ENDPOINTS_COLLECTION_SLUG, {limit: 0});
+    return entries
+        .filter(e => canSeeArtefact(user, {meta: {project: e.data?.project}}))
+        .map(sanitise);
+}
+
+/**
+ * Fetch a single endpoint, sanitised. Caller does the canSeeArtefact check.
+ *
+ * @param {string} id
+ * @returns {Promise<object|null>}
+ */
+export async function getEndpointSanitised(id) {
+    const entry = await getEntry(API_ENDPOINTS_COLLECTION_SLUG, id);
+    return entry ? sanitise(entry) : null;
+}
+
+/**
+ * Look up an endpoint by project + path SHAPE (`:x` ≡ `:y`).
+ * Used for scaffolder idempotency.
+ *
+ * @param {string} project
+ * @param {string} path
+ * @returns {Promise<object|null>}
+ */
+export async function findEndpointByPath(project, path) {
+    const shape = pathShape(path);
+    const {entries} = await listEntries(API_ENDPOINTS_COLLECTION_SLUG, {limit: 0});
+    const entry = entries.find(e => e.data?.project === project && pathShape(e.data?.path || '') === shape);
+    return entry ? sanitise(entry) : null;
+}
+
+/**
+ * Build the compiled registry from enabled definitions. Within a project,
+ * endpoints sort by static-segment count descending so static paths beat
+ * `:param` paths when both match.
+ *
+ * @returns {Promise<Map<string, object[]>>}
+ */
+async function buildRegistry() {
+    const {entries} = await listEntries(API_ENDPOINTS_COLLECTION_SLUG, {limit: 0});
+    const map = new Map();
+    for (const entry of entries) {
+        const def = sanitise(entry);
+        if (!def.enabled || !def.project || !def.path) continue;
+        const segments = def.path.split('/').filter(Boolean).map(s =>
+            s.startsWith(':') ? {param: s.slice(1)} : {static: s}
+        );
+        const compiled = {
+            def,
+            segments,
+            staticCount: segments.filter(s => s.static).length
+        };
+        if (!map.has(def.project)) map.set(def.project, []);
+        map.get(def.project).push(compiled);
+    }
+    for (const list of map.values()) {
+        list.sort((a, b) => b.staticCount - a.staticCount);
+    }
+    return map;
+}
+
+/**
+ * Match a request path against the registry.
+ *
+ * @param {string}   project  - First wildcard segment
+ * @param {string[]} segments - Remaining wildcard segments (raw, URL-encoded)
+ * @returns {Promise<{def: object, params: Record<string, string>}|null>}
+ */
+export async function matchEndpoint(project, segments) {
+    if (!registry) registry = await buildRegistry();
+    const candidates = registry.get(project);
+    if (!candidates) return null;
+
+    outer:
+    for (const c of candidates) {
+        if (c.segments.length !== segments.length) continue;
+        const params = {};
+        for (let i = 0; i < c.segments.length; i++) {
+            const spec = c.segments[i];
+            if (spec.static !== undefined) {
+                if (spec.static !== segments[i]) continue outer;
+            } else {
+                try { params[spec.param] = decodeURIComponent(segments[i]); }
+                catch { params[spec.param] = segments[i]; }
+            }
+        }
+        return {def: c.def, params};
+    }
+    return null;
+}
+
+/**
+ * Substitute {{params.X}} / {{query.X}} placeholders in the definition's
+ * filter values. Unresolved params throw (route maps to 400); a clause whose
+ * {{query.X}} stays unresolved is DROPPED, so query placeholders act as
+ * optional refinements.
+ *
+ * @param {object} filterTemplate
+ * @param {Record<string, string>} params
+ * @param {Record<string, string>} query
+ * @returns {object} Concrete filter for the filterEngine
+ */
+function substituteFilter(filterTemplate, params, query) {
+    const out = {};
+    for (const [key, raw] of Object.entries(filterTemplate || {})) {
+        if (typeof raw !== 'string') { out[key] = raw; continue; }
+
+        let dropped = false;
+        const value = raw.replace(TEMPLATE_RE, (_m, kind, name) => {
+            const source = kind === 'params' ? params : query;
+            const v = source?.[name];
+            if (v === undefined || v === null || v === '') {
+                if (kind === 'params') {
+                    throw new EndpointParamError(`Missing required path parameter "${name}"`);
+                }
+                dropped = true;
+                return '';
+            }
+            return String(v);
+        });
+        if (!dropped) out[key] = value;
+    }
+    return out;
+}
+
+/**
+ * Execute a matched endpoint definition.
+ *
+ * @param {object} def
+ * @param {Record<string, string>} params - Decoded path params
+ * @param {Record<string, string>} query  - Request query object
+ * @returns {Promise<object|null>} list payload, single entry, or null (single miss)
+ * @throws {EndpointParamError}
+ */
+export async function executeEndpoint(def, params, query) {
+    const filter = substituteFilter(def.filter, params, query || {});
+    const result = await listEntries(def.collection, {
+        page: 1,
+        limit: def.mode === 'single' ? 1 : (def.limit ?? 50),
+        sort: def.sort || 'createdAt',
+        order: def.order || 'desc',
+        filter: Object.keys(filter).length ? filter : undefined
+    });
+    if (def.mode === 'single') return result.entries[0] || null;
+    return result;
+}