domma-cms 0.23.0 → 0.25.0

package/server/services/apiEndpoints.js

@@ -0,0 +1,402 @@
+/**
+ * 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 {canSeeArtefact, getProject} 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`);
+    }
+
+    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;
+}

package/server/services/apiTokens.js

@@ -0,0 +1,273 @@
+/**
+ * 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;
+
+/**
+ * Serialises this service's fire-and-forget writes (the throttled lastUsedAt
+ * update) against its mutations. FileAdapter does unlocked read-modify-write,
+ * so an in-flight lastUsedAt update that read the data file BEFORE a revoke
+ * wrote it would write the revoked token straight back — resurrection.
+ * Mutations await the chain; lastUsedAt updates append to it.
+ */
+let writeChain = Promise.resolve();
+
+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
+        // Fire-and-forget, but chained so revoke/update can await it.
+        writeChain = writeChain
+            .then(() => 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 = {}) {
+    await writeChain; // drain any in-flight lastUsedAt write first
+    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) {
+    await writeChain; // drain any in-flight lastUsedAt write — revoke must be final
+    const entry = await getEntry(API_TOKENS_COLLECTION_SLUG, id);
+    if (!entry) return false;
+    await deleteEntry(API_TOKENS_COLLECTION_SLUG, id);
+    invalidateCache();
+    return true;
+}