@directus/api 32.2.0 → 33.1.0

package/dist/websocket/collab/filter-to-fields.js

@@ -0,0 +1,11 @@
+import { deepMapFilter } from '@directus/utils';
+export function filterToFields(filter, collection, schema) {
+    const fields = new Set();
+    deepMapFilter(filter, ([key, _value], context) => {
+        if (context.leaf && context.field) {
+            fields.add([...context.path, key].join('.'));
+        }
+        return undefined;
+    }, { collection, schema });
+    return Array.from(fields);
+}

package/dist/websocket/collab/messenger.d.ts

@@ -0,0 +1,43 @@
+import type { Bus } from '@directus/memory';
+import { type WebSocketClient } from '@directus/types';
+import { type BroadcastMessage, type ClientID, type ServerError, type ServerMessage } from '@directus/types/collab';
+type Instance = {
+    clients: ClientID[];
+    rooms: string[];
+};
+type Registry = Record<string, Instance>;
+type RegistrySnapshot = {
+    inactive: Instance;
+    active: ClientID[];
+};
+type RoomMessage = Extract<BroadcastMessage, {
+    type: 'room';
+}>;
+export type RoomListener = (message: RoomMessage) => void;
+export declare class Messenger {
+    uid: `${string}-${string}-${string}-${string}-${string}`;
+    store: <T>(callback: (store: import("./store.js").RedisStore<{
+        instances: Registry;
+    }>) => Promise<T>) => Promise<T>;
+    clients: Record<ClientID, WebSocketClient>;
+    orders: Record<ClientID, number>;
+    messenger: Bus;
+    roomListeners: Record<string, RoomListener>;
+    constructor();
+    hasClient(client: ClientID): boolean;
+    setRoomListener(room: string, callback: RoomListener): void;
+    removeRoomListener(room: string): void;
+    addClient(client: WebSocketClient): void;
+    removeClient(uid: ClientID): void;
+    registerRoom(uid: string): Promise<void>;
+    unregisterRoom(uid: string): Promise<void>;
+    getLocalClients(): Promise<ClientID[]>;
+    getGlobalClients(): Promise<ClientID[]>;
+    pruneDeadInstances(): Promise<RegistrySnapshot>;
+    sendRoom(room: string, message: Omit<RoomMessage, 'type' | 'room'>): void;
+    sendClient(client: ClientID, message: Omit<ServerMessage, 'order'>): void;
+    terminateClient(client: ClientID): void;
+    sendError(client: ClientID, error: ServerError): void;
+    handleError(client: ClientID, error: unknown, action?: ServerError['trigger']): void;
+}
+export {};

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;