@directus/api 33.0.0 → 33.1.0

package/dist/websocket/collab/messenger.js

@@ -0,0 +1,225 @@
+import { randomUUID } from 'crypto';
+import { useEnv } from '@directus/env';
+import { isDirectusError } from '@directus/errors';
+import { WS_TYPE } from '@directus/types';
+import { COLLAB_BUS, } from '@directus/types/collab';
+import { useBus } from '../../bus/index.js';
+import { useLogger } from '../../logger/index.js';
+import { useStore } from './store.js';
+const env = useEnv();
+const INSTANCE_TIMEOUT = Number(env['WEBSOCKETS_COLLAB_INSTANCE_TIMEOUT']);
+export class Messenger {
+    uid;
+    store;
+    clients = {};
+    orders = {};
+    messenger = useBus();
+    roomListeners = {};
+    constructor() {
+        this.uid = randomUUID();
+        this.store = useStore('registry', { instances: {} });
+        this.store(async (store) => {
+            const instances = await store.get('instances');
+            instances[this.uid] = { clients: [], rooms: [] };
+            await store.set('instances', instances);
+        }).catch((err) => {
+            useLogger().error(err, '[Collab] Failed to register instance in registry');
+        });
+        this.messenger.subscribe(COLLAB_BUS, (message) => {
+            if (message.type === 'send') {
+                const client = this.clients[message.client];
+                if (client) {
+                    const order = this.orders[client.uid] ?? 0;
+                    this.orders[client.uid] = order + 1;
+                    client.send(JSON.stringify({ ...message.message, order }));
+                }
+            }
+            else if (message.type === 'error') {
+                const client = this.clients[message.client];
+                if (client) {
+                    client.send(JSON.stringify(message.message));
+                }
+            }
+            else if (message.type === 'terminate') {
+                this.clients[message.client]?.close();
+            }
+            else if (message.type === 'room') {
+                this.roomListeners[message.room]?.(message);
+            }
+            else if (message.type === 'ping' && message.instance === this.uid) {
+                this.messenger.publish(COLLAB_BUS, { type: 'pong', instance: this.uid });
+            }
+        });
+    }
+    hasClient(client) {
+        return client in this.clients;
+    }
+    setRoomListener(room, callback) {
+        this.roomListeners[room] = callback;
+    }
+    removeRoomListener(room) {
+        delete this.roomListeners[room];
+    }
+    addClient(client) {
+        if (client.uid in this.clients)
+            return;
+        this.clients[client.uid] = client;
+        this.orders[client.uid] = 0;
+        this.store(async (store) => {
+            const instances = await store.get('instances');
+            if (!instances[this.uid])
+                instances[this.uid] = { clients: [], rooms: [] };
+            instances[this.uid].clients = [...(instances[this.uid].clients ?? []), client.uid];
+            await store.set('instances', instances);
+        }).catch((err) => {
+            useLogger().error(err, `[Collab] Failed to add client ${client.uid} to registry`);
+        });
+        client.on('close', () => {
+            this.removeClient(client.uid);
+        });
+    }
+    removeClient(uid) {
+        delete this.clients[uid];
+        delete this.orders[uid];
+        this.store(async (store) => {
+            const instances = await store.get('instances');
+            if (instances[this.uid]) {
+                instances[this.uid].clients = (instances[this.uid].clients ?? []).filter((clientId) => clientId !== uid);
+                await store.set('instances', instances);
+            }
+        }).catch((err) => {
+            useLogger().error(err, `[Collab] Failed to remove client ${uid} from registry`);
+        });
+    }
+    async registerRoom(uid) {
+        await this.store(async (store) => {
+            const instances = await store.get('instances');
+            if (!instances[this.uid])
+                instances[this.uid] = { clients: [], rooms: [] };
+            if (!instances[this.uid].rooms.includes(uid)) {
+                instances[this.uid].rooms.push(uid);
+                await store.set('instances', instances);
+            }
+        });
+    }
+    async unregisterRoom(uid) {
+        await this.store(async (store) => {
+            const instances = await store.get('instances');
+            if (instances[this.uid]) {
+                instances[this.uid].rooms = (instances[this.uid].rooms ?? []).filter((roomUid) => roomUid !== uid);
+                await store.set('instances', instances);
+            }
+        });
+    }
+    async getLocalClients() {
+        return Object.keys(this.clients);
+    }
+    async getGlobalClients() {
+        const instances = await this.store(async (store) => await store.get('instances'));
+        return Object.values(instances)
+            .map((instance) => instance.clients)
+            .flat();
+    }
+    async pruneDeadInstances() {
+        const instances = await this.store(async (store) => await store.get('instances'));
+        const inactiveInstances = new Set(Object.keys(instances));
+        inactiveInstances.delete(this.uid);
+        const pongCollector = (message) => {
+            if (message.type === 'pong') {
+                inactiveInstances.delete(message.instance);
+            }
+        };
+        this.messenger.subscribe(COLLAB_BUS, pongCollector);
+        for (const instance of inactiveInstances) {
+            this.messenger.publish(COLLAB_BUS, { type: 'ping', instance });
+        }
+        await new Promise((resolve) => {
+            setTimeout(resolve, INSTANCE_TIMEOUT);
+        });
+        this.messenger.unsubscribe(COLLAB_BUS, pongCollector);
+        const dead = { clients: [], rooms: [] };
+        if (inactiveInstances.size === 0) {
+            return {
+                inactive: dead,
+                active: Object.values(instances)
+                    .map((instance) => instance.clients)
+                    .flat(),
+            };
+        }
+        // Reread state to avoid overwriting updates during the timeout phase
+        const current = await this.store(async (store) => {
+            const current = await store.get('instances');
+            let changed = false;
+            for (const deadId of inactiveInstances) {
+                if (current[deadId]) {
+                    dead.clients.push(...(current[deadId].clients ?? []));
+                    dead.rooms.push(...(current[deadId].rooms ?? []));
+                    delete current[deadId];
+                    changed = true;
+                }
+            }
+            if (changed) {
+                await store.set('instances', current);
+            }
+            return current;
+        });
+        return {
+            inactive: dead,
+            active: Object.values(current)
+                .map((instance) => instance.clients)
+                .flat(),
+        };
+    }
+    sendRoom(room, message) {
+        this.messenger.publish(COLLAB_BUS, { type: 'room', room, ...message });
+    }
+    sendClient(client, message) {
+        const localClient = this.clients[client];
+        if (localClient) {
+            const order = this.orders[client] ?? 0;
+            this.orders[client] = order + 1;
+            localClient.send(JSON.stringify({ ...message, order }));
+        }
+        else {
+            this.messenger.publish(COLLAB_BUS, { type: 'send', client, message });
+        }
+    }
+    terminateClient(client) {
+        const localClient = this.clients[client];
+        if (localClient) {
+            // Allow message to flush before closing
+            setTimeout(() => {
+                localClient.close();
+            }, 250);
+        }
+        else {
+            this.messenger.publish(COLLAB_BUS, { type: 'terminate', client });
+        }
+    }
+    sendError(client, error) {
+        const localClient = this.clients[client];
+        if (localClient) {
+            localClient.send(JSON.stringify(error));
+        }
+        else {
+            this.messenger.publish(COLLAB_BUS, { type: 'error', client, message: error });
+        }
+    }
+    handleError(client, error, action) {
+        let message;
+        if (isDirectusError(error)) {
+            message = {
+                action: 'error',
+                type: WS_TYPE.COLLAB,
+                code: error.code,
+                trigger: action,
+                message: error.message,
+            };
+        }
+        else {
+            useLogger().error(`WebSocket unhandled exception ${JSON.stringify({ type: WS_TYPE.COLLAB, error })}`);
+            return;
+        }
+        this.sendError(client, message);
+    }
+}

package/dist/websocket/collab/payload-permissions.d.ts

@@ -0,0 +1,18 @@
+import type { Accountability, PrimaryKey, SchemaOverview } from '@directus/types';
+import type { Knex } from 'knex';
+type PermissionContext = {
+    knex: Knex;
+    schema: SchemaOverview;
+    accountability: Accountability | null;
+    itemId?: PrimaryKey | null;
+    direction?: 'inbound' | 'outbound';
+};
+/**
+ * Validates a changes payload against the user's update/create permissions and errors if unauthorized field is encountered
+ */
+export declare function validateChanges(payload: any, collection: string, itemId: PrimaryKey | null, context: PermissionContext): Promise<any>;
+/**
+ * Sanitizes a payload based on the recipient's read permissions and the schema
+ */
+export declare function sanitizePayload(payload: any, collection: string, context: PermissionContext): Promise<any>;
+export {};

package/dist/websocket/collab/payload-permissions.js

@@ -0,0 +1,158 @@
+import { ForbiddenError, InvalidPayloadError } from '@directus/errors';
+import { deepMapWithSchema, isDetailedUpdateSyntax } from '@directus/utils';
+import { verifyPermissions } from './verify-permissions.js';
+/**
+ * Validates a changes payload against the user's update/create permissions and errors if unauthorized field is encountered
+ */
+export async function validateChanges(payload, collection, itemId, context) {
+    return processPermissions(payload, collection, { ...context, itemId, direction: 'inbound' });
+}
+/**
+ * Sanitizes a payload based on the recipient's read permissions and the schema
+ */
+export async function sanitizePayload(payload, collection, context) {
+    return processPermissions(payload, collection, { ...context, direction: 'outbound' });
+}
+/**
+ * Core utility to walk a payload and apply permissions
+ */
+async function processPermissions(payload, collection, context) {
+    const { direction, accountability, schema, knex, itemId } = context;
+    // Local cache for permissions to avoid redundant verifyPermissions calls for the same item:action pair
+    // The promise is cached, so concurrent field lookups for the same item wait for the same result
+    const permissionsCache = new Map();
+    const getPermissions = (col, id, action) => {
+        const cacheKey = `${col}:${id}:${action}`;
+        let cached = permissionsCache.get(cacheKey);
+        if (!cached) {
+            cached = verifyPermissions(accountability, col, id, action, { knex, schema });
+            permissionsCache.set(cacheKey, cached);
+        }
+        return cached;
+    };
+    return deepMapWithSchema(payload, async (entry, deepMapContext) => {
+        const [key, value] = entry;
+        if (direction === 'outbound') {
+            // Strip sensitive fields
+            if (deepMapContext.field?.special?.some((v) => v === 'conceal' || v === 'hash' || v === 'encrypt')) {
+                return undefined;
+            }
+            // Strip unknown leaf fields
+            if (deepMapContext.leaf && !deepMapContext.relation && !deepMapContext.field) {
+                return undefined;
+            }
+        }
+        if (value === undefined)
+            return undefined;
+        // Resolve the action (CRUD) and the ID to check against
+        const currentCollection = deepMapContext.collection.collection;
+        const pkField = deepMapContext.collection.primary;
+        const primaryKeyInObject = (deepMapContext.object[pkField] ?? null);
+        let action = direction === 'inbound' ? 'update' : 'read';
+        let effectiveItemId = primaryKeyInObject;
+        if (direction === 'inbound') {
+            const isTopLevel = deepMapContext.object === payload;
+            // At the top level, we use the ID from the request context (itemId)
+            // Deeply nested objects must provide their own ID for update checks
+            if (isTopLevel) {
+                effectiveItemId = itemId ?? null;
+                action = itemId ? 'update' : 'create';
+            }
+            else if (!primaryKeyInObject) {
+                action = 'create';
+            }
+            if (deepMapContext.action) {
+                action = deepMapContext.action;
+            }
+        }
+        else {
+            // sanitizePayload uses context.itemId as a fallback for the root item
+            if (deepMapContext.object === payload) {
+                effectiveItemId = primaryKeyInObject ?? itemId ?? null;
+            }
+        }
+        // Ensure no unexpected fields sneak into a delete operation
+        if (direction === 'inbound' && action === 'delete') {
+            if (key !== pkField) {
+                throw new InvalidPayloadError({ reason: `Unexpected field ${key} in delete payload` });
+            }
+            const allowed = await getPermissions(currentCollection, primaryKeyInObject, 'delete');
+            if (allowed === null || (allowed.length === 0 && !accountability?.admin)) {
+                throw new ForbiddenError({ reason: `No permission to delete item in collection ${currentCollection}` });
+            }
+            return;
+        }
+        // Allow PK field for identification on updates
+        if (direction === 'inbound' && action === 'update' && key === pkField) {
+            return;
+        }
+        let allowedFields = await getPermissions(currentCollection, effectiveItemId, action);
+        // Fallbacks
+        if (!allowedFields) {
+            if (direction === 'inbound' && action === 'update') {
+                // Toggle to create if update fails due to non-existence
+                action = 'create';
+                allowedFields = await getPermissions(currentCollection, effectiveItemId, action);
+            }
+            else if (direction === 'outbound') {
+                // Fall back to collection-wide read
+                allowedFields = (await getPermissions(currentCollection, null, 'read')) ?? [];
+            }
+        }
+        const isAllowed = allowedFields && (accountability?.admin || allowedFields.includes('*') || allowedFields.includes(String(key)));
+        if (!isAllowed) {
+            if (direction === 'inbound') {
+                throw new ForbiddenError({ reason: `No permission to ${action} field ${key} or field does not exist` });
+            }
+            return undefined;
+        }
+        // Remove the relation field entirely from the payload if it's empty after sanitizing its children
+        if (direction === 'outbound' && deepMapContext.relationType) {
+            if (Array.isArray(value)) {
+                const items = value.filter(isVisible);
+                if (items.length === 0)
+                    return undefined;
+                return [key, items];
+            }
+            else if (isDetailedUpdateSyntax(value)) {
+                const filtered = {
+                    ...value,
+                    create: value.create.filter(isVisible),
+                    update: value.update.filter(isVisible),
+                    delete: value.delete.filter(isVisible),
+                };
+                if (filtered.create.length === 0 && filtered.update.length === 0 && filtered.delete.length === 0) {
+                    return undefined;
+                }
+                return [key, filtered];
+            }
+            else if (!isVisible(value)) {
+                return undefined;
+            }
+        }
+        return [key, value];
+    }, {
+        schema,
+        collection,
+    }, {
+        detailedUpdateSyntax: true,
+        omitUnknownFields: direction === 'outbound',
+        mapPrimaryKeys: true,
+        processAsync: true,
+        iterateOnly: direction === 'inbound', // Validation only needs to check permissions, not rebuild the payload
+        onUnknownField: (entry) => {
+            const [key] = entry;
+            // Allow Directus internal metadata keys like $type
+            if (String(key).startsWith('$'))
+                return entry;
+            if (direction === 'inbound') {
+                throw new ForbiddenError({ reason: `No permission to update field ${key} or field does not exist` });
+            }
+            return undefined;
+        },
+    });
+}
+// Identifies non-empty or defined actionable content to avoid processing invalid relation links
+function isVisible(item) {
+    return item !== undefined && !(typeof item === 'object' && item !== null && Object.keys(item).length === 0);
+}

package/dist/websocket/collab/permissions-cache.d.ts

@@ -0,0 +1,52 @@
+import type { Accountability } from '@directus/types';
+/**
+ * Caches permission check results for collaborative editing clients.
+ * Supports granular invalidation based on collection, item, and relational dependencies.
+ */
+export declare class PermissionCache {
+    private cache;
+    private tags;
+    private keyTags;
+    private timers;
+    private bus;
+    private invalidationCount;
+    constructor(maxSize: number);
+    /**
+     * Used for race condition protection during async permission fetches.
+     */
+    getInvalidationCount(): number;
+    /**
+     * Clears entire cache for system collections, or performs granular invalidation for user data.
+     */
+    private handleInvalidation;
+    /**
+     * Get cached allowed fields for a given accountability and collection/item.
+     * LRUMap automatically updates access order on get().
+     */
+    get(accountability: Accountability, collection: string, item: string | null, action: string): string[] | null | undefined;
+    /**
+     * Store allowed fields in the cache with optional TTL and dependencies.
+     */
+    set(accountability: Accountability, collection: string, item: string | null, action: string, fields: string[] | null, dependencies?: string[], ttlMs?: number): void;
+    /**
+     * Called before LRU eviction or explicit invalidation to prevent orphaned metadata.
+     */
+    private cleanupKeyMetadata;
+    /**
+     * Maintains bidirectional mappings: tag → keys and key → tags.
+     */
+    private addTag;
+    /**
+     * Cleans up metadata first, then removes from cache.
+     */
+    private invalidateKey;
+    /**
+     * Cache key format: user:collection:item:action
+     */
+    private getCacheKey;
+    /**
+     * Clear the entire cache.
+     */
+    clear(): void;
+}
+export declare const permissionCache: PermissionCache;

package/dist/websocket/collab/permissions-cache.js

@@ -0,0 +1,204 @@
+import { useEnv } from '@directus/env';
+import { LRUMapWithDelete } from 'mnemonist';
+import { useBus } from '../../bus/index.js';
+import { IRRELEVANT_COLLECTIONS } from './constants.js';
+const env = useEnv();
+/**
+ * Caches permission check results for collaborative editing clients.
+ * Supports granular invalidation based on collection, item, and relational dependencies.
+ */
+export class PermissionCache {
+    cache;
+    tags = new Map();
+    keyTags = new Map();
+    timers = new Map();
+    bus = useBus();
+    invalidationCount = 0;
+    constructor(maxSize) {
+        this.cache = new LRUMapWithDelete(maxSize);
+        this.bus.subscribe('websocket.event', (event) => {
+            this.handleInvalidation(event);
+        });
+    }
+    /**
+     * Used for race condition protection during async permission fetches.
+     */
+    getInvalidationCount() {
+        return this.invalidationCount;
+    }
+    /**
+     * Clears entire cache for system collections, or performs granular invalidation for user data.
+     */
+    handleInvalidation(event) {
+        const { collection, keys, key } = event;
+        const items = keys || (key ? [key] : []);
+        const affectedKeys = new Set();
+        // System Invalidation (Roles, Permissions, Policies, Schema)
+        if ([
+            'directus_roles',
+            'directus_permissions',
+            'directus_policies',
+            'directus_access',
+            'directus_fields',
+            'directus_relations',
+            'directus_collections',
+        ].includes(collection)) {
+            this.clear();
+            return;
+        }
+        // Skip known high-traffic collections
+        if (IRRELEVANT_COLLECTIONS.includes(collection)) {
+            return;
+        }
+        this.invalidationCount++;
+        // Prevent overflow issues in long-running processes
+        if (this.invalidationCount >= Number.MAX_SAFE_INTEGER) {
+            this.invalidationCount = 1;
+        }
+        // Skip if no keys are watching
+        if (!this.tags.has(`collection:${collection}`) &&
+            !this.tags.has(`dependency:${collection}`) &&
+            !this.tags.has(`collection-dependency:${collection}`)) {
+            return;
+        }
+        // Collection-level Invalidation
+        if (items.length === 0 && this.tags.has(`collection:${collection}`)) {
+            for (const k of this.tags.get(`collection:${collection}`))
+                affectedKeys.add(k);
+        }
+        // Item-level Invalidation
+        for (const id of items) {
+            const tag = `item:${collection}:${id}`;
+            if (this.tags.has(tag)) {
+                for (const k of this.tags.get(tag))
+                    affectedKeys.add(k);
+            }
+        }
+        // Dependency Invalidation (Items + Relational)
+        const depTags = [`dependency:${collection}`];
+        if (items.length > 0) {
+            for (const id of items) {
+                depTags.push(`dependency:${collection}:${id}`);
+            }
+        }
+        else {
+            depTags.push(`collection-dependency:${collection}`);
+        }
+        for (const tag of depTags) {
+            if (this.tags.has(tag)) {
+                for (const k of this.tags.get(tag))
+                    affectedKeys.add(k);
+            }
+        }
+        for (const k of affectedKeys) {
+            this.invalidateKey(k);
+        }
+    }
+    /**
+     * Get cached allowed fields for a given accountability and collection/item.
+     * LRUMap automatically updates access order on get().
+     */
+    get(accountability, collection, item, action) {
+        const key = this.getCacheKey(accountability, collection, item, action);
+        return this.cache.get(key);
+    }
+    /**
+     * Store allowed fields in the cache with optional TTL and dependencies.
+     */
+    set(accountability, collection, item, action, fields, dependencies = [], ttlMs) {
+        const key = this.getCacheKey(accountability, collection, item, action);
+        // Clear existing timer if any
+        if (this.timers.has(key)) {
+            clearTimeout(this.timers.get(key));
+            this.timers.delete(key);
+        }
+        // Clean up metadata for LRU eviction if at capacity
+        // LRUMapWithDelete auto-evicts, but we need to clean up our tag mappings
+        if (!this.cache.has(key) && this.cache.size >= this.cache.capacity) {
+            const lruKey = this.cache.keys().next().value;
+            if (lruKey) {
+                this.cleanupKeyMetadata(lruKey);
+            }
+        }
+        this.cache.set(key, fields);
+        if (ttlMs) {
+            const timer = setTimeout(() => {
+                this.invalidateKey(key);
+            }, ttlMs);
+            this.timers.set(key, timer);
+        }
+        // Always tag the specific item
+        this.addTag(key, `item:${collection}:${item}`);
+        // Always tag the collection to cover batch updates
+        this.addTag(key, `collection:${collection}`);
+        // Add custom dependencies such as relational collections
+        for (const dep of dependencies) {
+            this.addTag(key, `dependency:${dep}`);
+            if (dep.includes(':')) {
+                const [dependencyCollection] = dep.split(':');
+                this.addTag(key, `collection-dependency:${dependencyCollection}`);
+            }
+        }
+    }
+    /**
+     * Called before LRU eviction or explicit invalidation to prevent orphaned metadata.
+     */
+    cleanupKeyMetadata(key) {
+        if (this.timers.has(key)) {
+            clearTimeout(this.timers.get(key));
+            this.timers.delete(key);
+        }
+        const tags = this.keyTags.get(key);
+        if (tags) {
+            for (const tag of tags) {
+                const keys = this.tags.get(tag);
+                if (keys) {
+                    keys.delete(key);
+                    if (keys.size === 0)
+                        this.tags.delete(tag);
+                }
+            }
+            this.keyTags.delete(key);
+        }
+    }
+    /**
+     * Maintains bidirectional mappings: tag → keys and key → tags.
+     */
+    addTag(key, tag) {
+        if (!this.tags.has(tag)) {
+            this.tags.set(tag, new Set());
+        }
+        this.tags.get(tag).add(key);
+        if (!this.keyTags.has(key)) {
+            this.keyTags.set(key, new Set());
+        }
+        this.keyTags.get(key).add(tag);
+    }
+    /**
+     * Cleans up metadata first, then removes from cache.
+     */
+    invalidateKey(key) {
+        this.cleanupKeyMetadata(key);
+        this.cache.delete(key);
+    }
+    /**
+     * Cache key format: user:collection:item:action
+     */
+    getCacheKey(accountability, collection, item, action) {
+        return `${accountability.user || 'public'}:${collection}:${item || 'singleton'}:${action}`;
+    }
+    /**
+     * Clear the entire cache.
+     */
+    clear() {
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        this.cache.clear();
+        this.tags.clear();
+        this.keyTags.clear();
+        this.invalidationCount++;
+    }
+}
+export const permissionCache = new PermissionCache(Number(env['WEBSOCKETS_COLLAB_PERMISSIONS_CACHE_CAPACITY'] ?? 2000));