@hitchy/plugin-odem-socket.io 0.2.3 → 0.3.0

package/api/services/odem/websocket-provider.js

@@ -1,16 +1,21 @@
 "use strict";
 
+const { promisify } = require( "node:util" );
+
 module.exports = function() {
 	const api = this;
 
-	const logDebug = api.log( "hitchy:odem:socket.io:debug" );
-	const logError = api.log( "hitchy:odem:socket.io:error" );
+	const logDebug = api.log( "hitchy:plugin:odem:socket.io:debug" );
+	const logInfo = api.log( "hitchy:plugin:odem:socket.io:info" );
+	const logError = api.log( "hitchy:plugin:odem:socket.io:error" );
 
 	/**
-	 * Implements API for controlling and monitoring server-side ODM via
-	 * websocket.
+	 * Implements API for controlling and monitoring server-side
+	 * document-oriented database via websocket.
 	 */
 	class OdemWebsocketProvider {
+		static #socketUsers = new Map();
+
 		/**
 		 * Integrates this provider with server-side websocket.
 		 *
@@ -19,183 +24,347 @@ module.exports = function() {
 		static start() {
 			api.once( "websocket", io => {
 				const { crud, notifications } = api.config.socket.odem;
-
 				const namespace = io.of( "/hitchy/odem" );
 
+
+				// - transmit notifications to clients ------------------------
+
 				const txPerModel = {};
 
 				for ( const [ modelName, model ] of Object.entries( api.models ) ) {
-					txPerModel[modelName] = this.broadcastModelNotifications( notifications, namespace, modelName, model );
+					if ( api.service.OdemSchema.mayBeExposed( { user: undefined }, model ) ) {
+						txPerModel[modelName] = this.broadcastModelNotifications( notifications, namespace, model );
+					}
 				}
 
-				namespace.on( "connection", socket => {
-					const rxPerModel = {};
-
-					for ( const [ modelName, model ] of Object.entries( api.models ) ) {
-						rxPerModel[modelName] = this.handleModelRequests( crud, socket, modelName, model );
-					}
+				api.once( "close", () => {
+					namespace.disconnectSockets( true );
 
-					socket.once( "disconnect", () => {
-						for ( const [ modelName, handlers ] of Object.entries( rxPerModel ) ) {
-							for ( const [ eventName, handler ] of Object.entries( handlers ) ) {
-								const prefix = api.utility.case.pascalToKebab( modelName );
+					for ( const [ modelName, handlers ] of Object.entries( txPerModel ) ) {
+						if ( handlers ) {
+							const model = api.models[modelName];
 
-								socket.off( `${prefix}:${eventName}`, handler );
-							}
+							model.notifications
+								.off( "created", handlers.created )
+								.off( "changed", handlers.changed )
+								.off( "removed", handlers.removed );
 						}
-					} );
+					}
 				} );
 
-				api.once( "close", () => {
-					namespace.disconnectSockets( true );
 
-					for ( const [ modelName, model ] of Object.entries( api.models ) ) {
-						const handlers = txPerModel[modelName];
+				// - receive requests from clients ----------------------------
 
-						model.notifications
-							.off( "created", handlers.created )
-							.off( "changed", handlers.changed )
-							.off( "removed", handlers.removed );
-					}
+				namespace.on( "connection", socket => {
+					this.getUserForSocket( socket );
+
+					const listener = ( query, ...args ) => this.handleControlRequest( crud, socket, query, args );
+
+					socket.onAny( listener );
+
+					socket.once( "disconnect", () => {
+						socket.offAny( listener );
+
+						this.#socketUsers.delete( socket.id );
+					} );
 				} );
 			} );
 		}
 
 		/**
-		 * Registers listeners for handling client-side events requesting
-		 * model-related actions.
+		 * Monitors models of document-oriented database and sends notifications
+		 * to connected clients in case items of either model have changed.
 		 *
 		 * @param {boolean} enabled true if command handling is enabled in configuration
-		 * @param {WebSocket} socket socket representing established incoming connection
-		 * @param {string} modelName name of model to manage
-		 * @param {class<Hitchy.Plugin.Odem.Model>} model ODM-based model instance to manage
-		 * @returns {Object<string,function>} map of registered handler functions
+		 * @param {Server} namespace namespace managing a list of server-side sockets with common prefix
+		 * @param {class<Hitchy.Plugin.Odem.Model>} Model model to monitor for change of items
+		 * @returns {Object<string,function>|undefined} map of registered handler functions
 		 */
-		static handleModelRequests( enabled, socket, modelName, model ) {
-			const prefix = api.utility.case.pascalToKebab( modelName );
-
-			if ( !enabled ) {
-				logDebug( "disabling socket-based action requests for model %s (%s)", modelName, prefix );
-
+		static broadcastModelNotifications( enabled, namespace, Model ) {
+			if ( enabled ) {
 				const handlers = {
-					list: ( _, __, ___, response ) => reject( response ),
-					find: ( _, __, ___, ____, response ) => reject( response ),
-					create: ( _, __, response ) => reject( response ),
-					read: ( _, __, response ) => reject( response ),
-					update: ( _, __, ___, response ) => reject( response ),
-					delete: ( _, __, response ) => reject( response ),
+					created: ( uuid, newRecord, asyncGeneratorFn ) => {
+						asyncGeneratorFn()
+							.then( item => this.namespaceEmit( namespace, Model, {
+								change: "created",
+								model: Model.name,
+								properties: item.toObject( { serialized: true } ),
+							}, true ) )
+							.catch( cause => {
+								logError( "broadcasting notification on having created item %s of %s has failed:", uuid, Model.name, cause.stack );
+							} );
+					},
+					changed: ( uuid, newRecord, oldRecord, asyncGeneratorFn ) => {
+						asyncGeneratorFn()
+							.then( item => this.namespaceEmit( namespace, Model, {
+								change: "updated",
+								model: Model.name,
+								properties: item.toObject( { serialized: true } ),
+							}, true ) )
+							.catch( cause => {
+								logError( "broadcasting notification on having updated item %s of %s has failed:", uuid, Model.name, cause.stack );
+							} );
+					},
+					removed: uuid => {
+						this.namespaceEmit( namespace, Model, {
+							change: "deleted",
+							model: Model.name,
+							properties: { uuid: Model.formatUUID( uuid ) },
+						}, false )
+							.catch( cause => {
+								logError( "broadcasting notification on having removed item %s of %s has failed:", uuid, Model.name, cause.stack );
+							} );
+					},
 				};
 
-				socket
-					.on( `${prefix}:list`, handlers.list )
-					.on( `${prefix}:find`, handlers.find )
-					.on( `${prefix}:create`, handlers.create )
-					.on( `${prefix}:read`, handlers.read )
-					.on( `${prefix}:update`, handlers.update )
-					.on( `${prefix}:delete`, handlers.delete );
+				Model.notifications
+					.on( "created", handlers.created )
+					.on( "changed", handlers.changed )
+					.on( "removed", handlers.removed );
 
 				return handlers;
 			}
 
-			logDebug( "enabling socket-based action requests for model %s (%s)", modelName, prefix );
+			return undefined;
+		}
 
-			const handlers = {
-				list: ( ...args ) => this.handleListRequest( modelName, model, ...args ),
-				find: ( ...args ) => this.handleFindRequest( modelName, model, ...args ),
-				create: ( ...args ) => this.handleCreateRequest( modelName, model, ...args ),
-				read: ( ...args ) => this.handleReadRequest( modelName, model, ...args ),
-				update: ( ...args ) => this.handleUpdateRequest( modelName, model, ...args ),
-				delete: ( ...args ) => this.handleDeleteRequest( modelName, model, ...args ),
-			};
+		/**
+		 * Reads promise for given socket's requesting user from local cache.
+		 *
+		 * This method is mocking Hitchy's request dispatching to invoke
+		 * policies of @hitchy/plugin-auth involved in setting up a requesting
+		 * user to be returned here eventually. The mocked request is based on
+		 * the provided socket's initial request.
+		 *
+		 * @param {WebSocket} socket socket to look up
+		 * @returns {Promise<User|undefined>} promise for user of provided socket
+		 */
+		static async getUserForSocket( socket ) {
+			if ( !this.#socketUsers.has( socket.id ) ) {
+				this.#socketUsers.set( socket.id, ( async _socket => {
+					if ( api.plugins.authentication ) {
+						const { SessionInjector, Cookies } = api.service;
+						const { Authentication } = api.policy;
+						const useSession = api.plugins.session && !api.config?.session?.disable;
+						const headers = _socket.request?.headers;
+
+						// mock context used by Hitchy for dispatching requests
+						const request = {
+							headers,
+							cookies: Cookies.parseFromString( headers?.cookie ),
+						};
+
+						const response = {
+							set: () => {}, // eslint-disable-line no-empty-function
+						};
+
+						const context = {
+							local: {},
+							updateSessionId: ( _, __, fn ) => fn(),
+						};
+
+						// invoke policies usually injecting a requesting user into a request
+						if ( useSession ) {
+							try {
+								await SessionInjector.injectIntoRequest( request, response );
+								await promisify( Authentication.injectPassport.bind( context ) )( request, response );
+							} catch ( cause ) {
+								logError( "mocking session-handling and passport injection has failed:", cause );
+							}
+						}
+
+						if ( !request.user ) {
+							try {
+								await promisify( Authentication.handleBasicAuth.bind( context ) )( request, response );
+							} catch ( cause ) {
+								logError( "mocking Basic authentication handling has failed:", cause );
+							}
+						}
+
+						// pick user eventually injected into mocked request
+						return request.user || undefined;
+					}
 
-			socket
-				.on( `${prefix}:list`, handlers.list )
-				.on( `${prefix}:find`, handlers.find )
-				.on( `${prefix}:create`, handlers.create )
-				.on( `${prefix}:read`, handlers.read )
-				.on( `${prefix}:update`, handlers.update )
-				.on( `${prefix}:delete`, handlers.delete );
+					return undefined;
+				} )( socket ) );
+			}
 
-			return handlers;
+			return await this.#socketUsers.get( socket.id );
 		}
 
 		/**
-		 * Sets up listeners for model-related notifications in ODM and forwards
-		 * them as broadcast events to connected clients.
+		 * Broadcasts a change notification to every connected peer in a given
+		 * namespace individually considering either peer's authorization for
+		 * accessing the changed model and/or its properties.
 		 *
-		 * @param {boolean} enabled true if command handling is enabled in configuration
-		 * @param {Server} namespace namespace managing a list of server-side sockets with common prefix
-		 * @param {string} modelName name of model to manage
-		 * @param {class<Hitchy.Plugin.Odem.Model>} model ODM-based model instance to manage
-		 * @returns {Object<string,function>} map of registered handler functions
+		 * @param {Server} namespace namespace managing a pool of sockets that have joined the namespace
+		 * @param {class<Hitchy.Plugin.Odem.Model>} Model model of changed item
+		 * @param {{change: string, model: string, properties: Object}} payload raw payload of model-specific notification
+		 * @param {boolean} filterProperties if true, properties need to be filtered per peer based on its authorization
+		 * @returns {Promise<void>} promise resolved when all authorized peers have been notified
 		 */
-		static broadcastModelNotifications( enabled, namespace, modelName, model ) {
-			if ( enabled ) {
-				const prefix = api.utility.case.pascalToKebab( modelName );
+		static async namespaceEmit( namespace, Model, payload, filterProperties ) {
+			const hasPluginAuth = Boolean( api.plugins.authentication );
+			const sockets = await namespace.fetchSockets();
 
-				const handlers = {
-					created: async( uuid, newRecord, asyncGeneratorFn ) => {
-						const event = {
-							change: "created",
-							properties: ( await asyncGeneratorFn() ).toObject( { serialized: true } ),
-						};
+			logDebug( "forwarding notification to %d socket(s)", sockets.length );
 
-						namespace.emit( `${prefix}:changed`, event );
-					},
-					changed: async( uuid, newRecord, oldRecord, asyncGeneratorFn ) => {
-						const event = {
-							change: "updated",
-							properties: ( await asyncGeneratorFn() ).toObject( { serialized: true } ),
-						};
+			const notifyPeer = async socket => {
+				const { OdemSchema, Authorization } = api.service;
+				let user;
 
-						namespace.emit( `${prefix}:changed`, event );
-					},
-					removed: uuid => {
-						const event = {
-							change: "deleted",
-							properties: { uuid: model.formatUUID( uuid ) },
-						};
+				try {
+					user = await this.#socketUsers.get( socket.id );
+				} catch ( cause ) {
+					logError( `discovering user of socket ${socket.id} has failed:`, cause );
+					return;
+				}
 
-						namespace.emit( `${prefix}:changed`, event );
-					},
-				};
+				if ( !OdemSchema.mayBeExposed( { user }, Model ) ) {
+					logDebug( `omit notification to user ${user?.uuid} (${user.name}) at peer ${socket.id} with access on ${Model.name} forbidden by model` );
+					return;
+				}
 
-				model.notifications
-					.on( "created", handlers.created )
-					.on( "changed", handlers.changed )
-					.on( "removed", handlers.removed );
+				let mayRead = OdemSchema.isAdmin( user );
+				let scope = "read";
 
-				return handlers;
+				if ( !mayRead && hasPluginAuth ) {
+					mayRead = await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.read` );
+
+					if ( !mayRead ) {
+						mayRead = await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.list` );
+						scope = "list";
+					}
+				}
+
+				const prefix = api.utility.case.pascalToKebab( Model.name );
+
+				if ( !mayRead ) {
+					// user must not read items of this model -> do not provide any identifier, but basically notify on some change to the model
+					socket.emit( `${prefix}:changed`, { ...payload, properties: {} } );
+					socket.emit( "*:changed", { ...payload, properties: {} } );
+				} else if ( filterProperties ) {
+					const copy = { ...payload };
+
+					copy.properties = OdemSchema.filterItem( copy.properties, { user }, Model, scope );
+
+					socket.emit( `${prefix}:changed`, copy );
+					socket.emit( "*:changed", copy );
+				} else {
+					socket.emit( `${prefix}:changed`, payload );
+					socket.emit( "*:changed", payload );
+				}
+			};
+
+			for ( const socket of sockets ) {
+				notifyPeer( socket ).catch( cause => {
+					logError(
+						`notifying peer ${socket.id} on having ${payload.change} item of ${Model.name} has failed:`,
+						cause.stack
+					);
+				} );
+			}
+		}
+
+		/**
+		 * Commonly handles incoming messages to process those requesting
+		 * supported control actions on existing models.
+		 *
+		 * @param {boolean} enabled if true, this plugin's control API has been enabled in configuration
+		 * @param {WebSocket} socket request-receiving socket
+		 * @param {string} query name of event that has been emitted by peer socket to request some action
+		 * @param {any[]} args arguments of incoming request and a callback for sending a response in final argument
+		 * @returns {void}
+		 */
+		static handleControlRequest( enabled, socket, query, args ) {
+			const match = /^([a-zA-Z][a-zA-Z0-9]+):(list|find|create|read|write|update|remove|delete)$/.exec( query );
+
+			if ( !match ) {
+				logDebug( "ignoring socket-based request %s due to mismatching format", query );
+				return;
+			}
+
+			const [ , prefix, action ] = match;
+			const modelName = api.utility.case.kebabToPascal( prefix );
+			const Model = api.model[modelName];
+
+			if ( !Model ) {
+				logDebug( "rejecting socket-based request %s due to addressing unknown model %s", query, modelName );
+
+				args[args.length - 1]( {
+					error: "no such model " + modelName,
+				} );
+				return;
 			}
 
-			return {};
+			const handler = {
+				list: "handleListRequest",
+				find: "handleFindRequest",
+				create: "handleCreateRequest",
+				read: "handleReadRequest",
+				write: "handleUpdateRequest",
+				update: "handleUpdateRequest",
+				remove: "handleDeleteRequest",
+				delete: "handleDeleteRequest",
+			}[action];
+
+			if ( !handler ) {
+				logDebug( "ignoring socket-based request for actin %s on model %s due to lack of handler", action, Model.name );
+				return;
+			}
+
+			if ( enabled ) {
+				this[handler]( socket, Model, ...args );
+			} else {
+				logDebug( "rejecting socket-based request for action %s on model %s", action, Model.name );
+
+				reject( args[args.length - 1] );
+			}
 		}
 
 		/**
 		 * Handles incoming request for listing items of a model.
 		 *
-		 * @param {string} modelName name of model
-		 * @param {string} model named server-side model
-		 * @param {string} sessionId client-provided session ID
+		 * @param {WebSocket} socket receiving socket of request
+		 * @param {class<Hitchy.Plugin.Odem.Model>} Model named server-side model
 		 * @param {Hitchy.Odem.ListOptions} queryOptions client-provided options for listing items
 		 * @param {boolean} loadRecords if true, whole records shall be fetched per item
 		 * @param {function} response callback to invoke with response
 		 * @returns {Promise<void>} promise settled on request handled
 		 */
-		static async handleListRequest( modelName, model, sessionId, queryOptions, loadRecords, response ) {
-			logDebug( "request for listing %s instances w/ queryOptions %j and loadRecords %j", modelName, queryOptions, Boolean( loadRecords ) );
+		static async handleListRequest( socket, Model, queryOptions, loadRecords, response ) {
+			logDebug( "request for listing %s instances w/ queryOptions %j and loadRecords %j", Model.name, queryOptions, Boolean( loadRecords ) );
 
 			try {
+				const user = await this.getUserForSocket( socket );
+
+				if ( api.plugins.authentication ) {
+					if ( !await api.service.Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.list` ) ) {
+						throw new Error( "access forbidden" );
+					}
+				}
+
+				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+					throw new Error( "access forbidden by model" );
+				}
+
 				const meta = {};
-				const items = await model.list( queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
+				const items = await Model.list( queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
+				let filter;
+
+				if ( loadRecords ) {
+					filter = item => api.service.OdemSchema.filterItem( item.toObject( { serialized: true } ), { user }, Model, "list" );
+				} else {
+					filter = item => ( { uuid: item.uuid } );
+				}
 
 				response( {
 					success: true,
 					count: meta.count,
-					items: items.map( item => ( loadRecords ? item.toObject( { serialized: true } ) : { uuid: item.uuid } ) ),
+					items: items.map( filter ),
 				} );
 			} catch ( error ) {
-				logError( "listing %s instances failed: %s", modelName, error.stack );
+				logError( "listing %s instances failed: %s", Model.name, error.stack );
 
 				response( {
 					error: error.message,
@@ -207,29 +376,47 @@ module.exports = function() {
 		 * Handles incoming request for finding items of a model matching some
 		 * provided query.
 		 *
-		 * @param {string} modelName name of model
-		 * @param {string} model named server-side model
-		 * @param {string} sessionId client-provided session ID
+		 * @param {WebSocket} socket receiving socket of request
+		 * @param {class<Hitchy.Plugin.Odem.Model>} Model named server-side model
 		 * @param {Hitchy.Odem.Query} query client-provided constraints to be met by returned items
 		 * @param {Hitchy.Odem.ListOptions} queryOptions client-provided options for listing items
 		 * @param {boolean} loadRecords if true, whole records shall be fetched per item
 		 * @param {function} response callback to invoke with response
 		 * @returns {Promise<void>} promise settled on request handled
 		 */
-		static async handleFindRequest( modelName, model, sessionId, query, queryOptions, loadRecords, response ) {
-			logDebug( "request for finding %s instances matching %j w/ queryOptions %j and uuidsOnly %j", modelName, query, queryOptions, Boolean( loadRecords ) );
+		static async handleFindRequest( socket, Model, query, queryOptions, loadRecords, response ) {
+			logDebug( "request for finding %s instances matching %j w/ queryOptions %j and uuidsOnly %j", Model.name, query, queryOptions, Boolean( loadRecords ) );
 
 			try {
+				const user = await this.getUserForSocket( socket );
+
+				if ( api.plugins.authentication ) {
+					if ( !await api.service.Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.list` ) ) {
+						throw new Error( "access forbidden" );
+					}
+				}
+
+				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+					throw new Error( "access forbidden by model" );
+				}
+
 				const meta = {};
-				const items = await model.find( query, queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
+				const items = await Model.find( query, queryOptions, { loadRecords: Boolean( loadRecords ), metaCollector: meta } );
+				let filter;
+
+				if ( loadRecords ) {
+					filter = item => api.service.OdemSchema.filterItem( item.toObject( { serialized: true } ), { user }, Model, "list" );
+				} else {
+					filter = item => ( { uuid: item.uuid } );
+				}
 
 				response( {
 					success: true,
 					count: meta.count,
-					items: items.map( item => ( loadRecords ? item.toObject( { serialized: true } ) : { uuid: item.uuid } ) ),
+					items: items.map( filter ),
 				} );
 			} catch ( error ) {
-				logError( "finding %s instances matching %j failed: %s", modelName, error.stack );
+				logError( "finding %s instances matching %j failed: %s", Model.name, query, error.stack );
 
 				response( {
 					error: error.message,
@@ -240,24 +427,35 @@ module.exports = function() {
 		/**
 		 * Handles incoming request for creating item of a model.
 		 *
-		 * @param {string} modelName name of model
-		 * @param {string} model named server-side model
-		 * @param {string} sessionId client-provided session ID
+		 * @param {WebSocket} socket receiving socket of request
+		 * @param {class<Hitchy.Plugin.Odem.Model>} Model named server-side model
 		 * @param {Hitchy.Odem.ListOptions} properties properties of item to create
 		 * @param {function} response callback to invoke with response
 		 * @returns {Promise<void>} promise settled on request handled
 		 */
-		static async handleCreateRequest( modelName, model, sessionId, properties, response ) {
-			logDebug( "request for creating %s instance with %j", modelName, properties );
+		static async handleCreateRequest( socket, Model, properties, response ) {
+			logDebug( "request for creating %s instance with %j", Model.name, properties );
+
+			const { Authorization, OdemSchema } = api.service;
 
 			try {
-				const schema = model.schema;
-				const instance = new model; // eslint-disable-line new-cap
+				const user = await this.getUserForSocket( socket );
+
+				if ( api.plugins.authentication && !await Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.create` ) ) {
+					throw new Error( "access forbidden" );
+				}
+
+				if ( !OdemSchema.mayBeExposed( { user }, Model ) ) {
+					throw new Error( "access forbidden by model" );
+				}
+
+				const schema = Model.schema;
+				const filtered = OdemSchema.filterItem( properties, { user }, Model, "create" );
+				const instance = new Model();
 
-				for ( const propName of Object.keys( properties ) ) {
-					if ( schema.props.hasOwnProperty( propName ) ||
-					     schema.computed.hasOwnProperty( propName ) ) {
-						instance[propName] = properties[propName];
+				for ( const [ propName, propValue ] of Object.entries( filtered ) ) {
+					if ( schema.props.hasOwnProperty( propName ) || schema.computed.hasOwnProperty( propName ) ) {
+						instance[propName] = propValue;
 					}
 				}
 
@@ -265,10 +463,10 @@ module.exports = function() {
 
 				response( {
 					success: true,
-					properties: instance.toObject( { serialized: true } ),
+					properties: OdemSchema.filterItem( instance.toObject( { serialized: true } ), { user }, Model, "read" ),
 				} );
 			} catch ( error ) {
-				logError( "creating %s instance failed: %s", modelName, error.stack );
+				logError( "creating %s instance failed: %s", Model.name, error.stack );
 
 				response( {
 					error: error.message,
@@ -279,26 +477,37 @@ module.exports = function() {
 		/**
 		 * Handles incoming request for reading properties of a single item.
 		 *
-		 * @param {string} modelName name of item's model
-		 * @param {string} model named server-side model
-		 * @param {string} sessionId client-provided session ID
+		 * @param {WebSocket} socket receiving socket of request
+		 * @param {class<Hitchy.Plugin.Odem.Model>} Model named server-side model
 		 * @param {string} uuid client-provided UUID of item to read
 		 * @param {function} response callback to invoke with response
 		 * @returns {Promise<void>} promise settled on request handled
 		 */
-		static async handleReadRequest( modelName, model, sessionId, uuid, response ) {
-			logDebug( "request for reading %s instance %s", modelName, uuid );
+		static async handleReadRequest( socket, Model, uuid, response ) {
+			logDebug( "request for reading %s instance %s", Model.name, uuid );
 
 			try {
-				const instance = new model( uuid ); // eslint-disable-line new-cap
+				const user = await this.getUserForSocket( socket );
+
+				if ( api.plugins.authentication ) {
+					if ( !await api.service.Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.read` ) ) {
+						throw new Error( "access forbidden" );
+					}
+				}
+
+				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+					throw new Error( "access forbidden by model" );
+				}
+
+				const instance = new Model( uuid );
 				await instance.load();
 
 				response( {
 					success: true,
-					properties: instance.toObject( { serialized: true } ),
+					properties: api.service.OdemSchema.filterItem( instance.toObject( { serialized: true } ), { user }, Model, "read" ),
 				} );
 			} catch ( error ) {
-				logError( "reading %s instance failed: %s", modelName, error.stack );
+				logError( "reading %s instance failed: %s", Model.name, error.stack );
 
 				response( {
 					error: error.message,
@@ -309,24 +518,37 @@ module.exports = function() {
 		/**
 		 * Handles incoming request for adjusting properties of a single item.
 		 *
-		 * @param {string} modelName name of item's model
-		 * @param {string} model named server-side model
-		 * @param {string} sessionId client-provided session ID
+		 * @param {WebSocket} socket receiving socket of request
+		 * @param {class<Hitchy.Plugin.Odem.Model>} Model named server-side model
 		 * @param {string} uuid client-provided UUID of item to modify
 		 * @param {Object} properties client-provided properties of item replacing its existing ones
 		 * @param {function} response callback to invoke with response
 		 * @returns {Promise<void>} promise settled on request handled
 		 */
-		static async handleUpdateRequest( modelName, model, sessionId, uuid, properties, response ) {
-			logDebug( "request for updating %s instance %s with %j", modelName, uuid, properties );
+		static async handleUpdateRequest( socket, Model, uuid, properties, response ) {
+			logDebug( "request for updating %s instance %s with %j", Model.name, uuid, properties );
 
 			try {
-				const instance = new model( uuid ); // eslint-disable-line new-cap
+				const user = await this.getUserForSocket( socket );
+
+				if ( api.plugins.authentication ) {
+					if ( !await api.service.Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.write` ) ) {
+						throw new Error( "access forbidden" );
+					}
+				}
+
+				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+					throw new Error( "access forbidden by model" );
+				}
+
+				const schema = Model.schema;
+				const filtered = api.service.OdemSchema.filterItem( properties, { user }, Model, "write" );
+				const instance = new Model( uuid );
 				await instance.load();
 
-				for ( const propName of Object.keys( properties ) ) {
-					if ( model.schema.props.hasOwnProperty( propName ) || model.schema.computed.hasOwnProperty( propName ) ) {
-						instance[propName] = properties[propName];
+				for ( const [ propName, propValue ] of Object.entries( filtered ) ) {
+					if ( schema.props.hasOwnProperty( propName ) || schema.computed.hasOwnProperty( propName ) ) {
+						instance[propName] = propValue;
 					}
 				}
 
@@ -334,10 +556,10 @@ module.exports = function() {
 
 				response( {
 					success: true,
-					properties: instance.toObject( { serialized: true } ),
+					properties: api.service.OdemSchema.filterItem( instance.toObject( { serialized: true } ), { user }, Model, "read" ),
 				} );
 			} catch ( error ) {
-				logError( "updating %s instance failed: %s", modelName, error.stack );
+				logError( "updating %s instance failed: %s", Model.name, error.stack );
 
 				response( {
 					error: error.message,
@@ -348,18 +570,29 @@ module.exports = function() {
 		/**
 		 * Handles incoming request for removing a model's item.
 		 *
-		 * @param {string} modelName name of item's model
-		 * @param {string} model named server-side model
-		 * @param {string} sessionId client-provided session ID
+		 * @param {WebSocket} socket receiving socket of request
+		 * @param {class<Hitchy.Plugin.Odem.Model>} Model named server-side model
 		 * @param {string} uuid client-provided UUID of item to remove
 		 * @param {function} response callback to invoke with response
 		 * @returns {Promise<void>} promise settled on request handled
 		 */
-		static async handleDeleteRequest( modelName, model, sessionId, uuid, response ) {
-			logDebug( "request for deleting %s instance %s", modelName, uuid );
+		static async handleDeleteRequest( socket, Model, uuid, response ) {
+			logDebug( "request for deleting %s instance %s", Model.name, uuid );
 
 			try {
-				const instance = new model( uuid ); // eslint-disable-line new-cap
+				const user = await this.getUserForSocket( socket );
+
+				if ( api.plugins.authentication ) {
+					if ( !await api.service.Authorization.mayAccess( user, `@hitchy.odem.model.${Model.name}.remove` ) ) {
+						throw new Error( "access forbidden" );
+					}
+				}
+
+				if ( !api.service.OdemSchema.mayBeExposed( { user }, Model ) ) {
+					throw new Error( "access forbidden by model" );
+				}
+
+				const instance = new Model( uuid );
 				await instance.remove();
 
 				response( {
@@ -367,7 +600,7 @@ module.exports = function() {
 					properties: { uuid },
 				} );
 			} catch ( error ) {
-				logError( "deleting %s instance %s failed: %s", modelName, uuid, error.stack );
+				logError( "deleting %s instance %s failed: %s", Model.name, uuid, error.stack );
 
 				response( {
 					error: error.message,

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "@hitchy/plugin-odem-socket.io",
-	"version": "0.2.3",
-	"description": "exposing Hitchy's ODM via websocket",
+	"version": "0.3.0",
+	"description": "exposing Hitchy's document-oriented database via websocket",
 	"main": "index.js",
 	"scripts": {
 		"lint": "eslint .",
-		"test": "hitchy-pm odem socket.io --exec mocha --ui=tdd 'test/**/*.spec.js*'",
-		"coverage": "hitchy-pm odem socket.io --exec c8 mocha --ui=tdd 'test/**/*.spec.js*'"
+		"test": "hitchy-pm odem socket.io auth --exec mocha --ui=tdd 'test/**/*.spec.js'",
+		"coverage": "hitchy-pm odem socket.io auth --exec c8 mocha --ui=tdd 'test/**/*.spec.js'"
 	},
 	"repository": {
 		"type": "git",
@@ -14,8 +14,7 @@
 	},
 	"keywords": [
 		"Hitchy",
-		"socket.io",
-		"ODM"
+		"socket.io"
 	],
 	"author": "cepharum GmbH",
 	"license": "MIT",
@@ -31,17 +30,17 @@
 	],
 	"peerDependencies": {
 		"@hitchy/core": ">=0.8.1",
-		"@hitchy/plugin-odem": ">=0.7.8",
+		"@hitchy/plugin-odem": ">=0.9.1",
 		"@hitchy/plugin-socket.io": ">=0.1.1"
 	},
 	"devDependencies": {
-		"@hitchy/server-dev-tools": "^0.4.6",
-		"c8": "^8.0.1",
-		"eslint": "^8.47.0",
-		"eslint-config-cepharum": "^1.0.13",
-		"eslint-plugin-promise": "^6.1.1",
-		"mocha": "^10.2.0",
+		"@hitchy/server-dev-tools": "^0.4.9",
+		"c8": "^10.1.2",
+		"eslint": "^8.57.0",
+		"eslint-config-cepharum": "^1.0.14",
+		"eslint-plugin-promise": "^7.1.0",
+		"mocha": "^10.7.3",
 		"should": "^13.2.3",
-		"socket.io-client": "^4.7.2"
+		"socket.io-client": "^4.7.5"
 	}
 }

package/readme.md

@@ -1,6 +1,6 @@
 # @hitchy/plugin-odem-socket.io
 
-_exposing Hitchy's ODM via websocket_
+_exposing Hitchy's document-oriented database via websocket_
 
 ## License
 
@@ -25,11 +25,17 @@ npm i @hitchy/plugin-odem @hitchy/plugin-socket.io
 
 * The parameter `uuidsOnly` of actions `<modelName>:list` and `<modelName>:find` has been replaced by `loadRecords` to match the semantics of server-side Odem API. You have to negate its value to adapt.
 
+### v0.3
+
+* This version is recognizing an existing authentication plugin and checks a user's authorization for accessing models and their properties based on authorization rules set on server.
+* Previously, actions of control API required the provision of a session ID to read a requesting user from as first argument. This approach has been abandoned. All actions are automatically associated with the user which has been authenticated when the websocket connection has been established.
+* Clients should drop and re-connect over websocket whenever authentication of a requesting user has changed.
+
 ## Usage
 
 ### Basics
 
-This plugin is establishing an API via websocket for controlling and monitoring models of server-side ODM. Relying on particular features of [socket.io](https://socket.io/), this API is exposed in [namespace](https://socket.io/docs/v4/namespaces/) `/hitchy/odem`. 
+This plugin is exposing an API via websocket for controlling and monitoring models of server-side document-oriented database. Relying on particular features of [socket.io](https://socket.io/), this API is exposed in [namespace](https://socket.io/docs/v4/namespaces/) `/hitchy/odem`. 
 
 For every server-side model, request listeners and/or notification broadcasters are set up. Either model's name is converted into its kebab-case variant and used as colon-separated prefix in event names emitted either by the server or by a client. 
 
@@ -47,7 +53,7 @@ All action events listed in this section are to be sent by a client. The server
 const socket = io( "/hitchy/odem" );
 
 socket.on( "connect", () => {
-    socket.emit( actionName, sessionId, arg1, arg2, arg3, response => {
+    socket.emit( actionName, arg1, arg2, arg3, response => {
         // process the response here
     } );
 } );
@@ -57,20 +63,17 @@ socket.on( "connect", () => {
 
 The following code excerpts are focusing on the inner part of emitting an action event and processing the response.
 
-In all these examples, a _sessionId_ is given. This is the current user's session ID usually found in a cookie set by a preceding HTTP request to authenticate the user. It is required on all requests to re-authenticate the user and to apply authorization checks to either request. It is okay to provide `null` here, however this might cause requests to be rejected based on server-side configuration.
-
 #### &lt;modelName>:list
 
 This request is the websocket variant of [Model.list()](https://odem.hitchy.org/api/model.html#model-list). Supported arguments are 
 
-* the session ID,
 * [query-related options](https://odem.hitchy.org/api/model.html#query-related-options) as supported by `Model.list()` and
 * a boolean controlling `loadRecords` of [result-related options](https://odem.hitchy.org/api/model.html#result-related-options) supported by `Model.list()`. 
 
-  > This boolean must be `true` to actually get all properties of retrieved items. Otherwise, listed items are represented by their UUIDs, only.
+  > This boolean must be `true` to actually get the properties of retrieved items. Otherwise, listed items are represented by their UUIDs, only.
 
 ```javascript
-socket.emit( "<modelName>:list", sessionId, { limit: 10 }, false, response => {
+socket.emit( "<modelName>:list", { limit: 10 }, false, response => {
     // - check for `response.success` or `response.error`
     // - process total count of items in `response.count`
     // - process requested excerpt of items in `response.items`
@@ -83,15 +86,14 @@ Last argument is a callback to be invoked with the resulting response from serve
 
 This request is searching for instances of selected model matching some query. It is invoking [Model.find()](https://odem.hitchy.org/api/model.html#model-find). Arguments are
 
-* the session ID,
 * the [query](https://odem.hitchy.org/api/model.html#model-find) describing items to find,
 * [query-related options](https://odem.hitchy.org/api/model.html#query-related-options) as supported by `Model.find()` and
 * a boolean controlling `loadRecords` of [result-related options](https://odem.hitchy.org/api/model.html#result-related-options) supported by `Model.find()`.
 
-  > This boolean must be `true` to actually get all properties of retrieved items. Otherwise, listed items are represented by their UUIDs, only.
+  > This boolean must be `true` to actually get the properties of retrieved items. Otherwise, listed items are represented by their UUIDs, only.
 
 ```javascript
-socket.emit( "<modelName>:find", sessionId, {}, { limit: 10 }, true, response => {
+socket.emit( "<modelName>:find", {}, { limit: 10 }, true, response => {
     // - check for `response.success` or `response.error`
     // - process total count of items in `response.count`
     // - process requested excerpt of items in `response.items`
@@ -102,10 +104,10 @@ Last argument is a callback to be invoked with the resulting response from serve
 
 #### &lt;modelName>:create
 
-This request is creating another instance of selected model assigning provided properties as initial values. Properties of instance to create are provided as serializable object in argument following the session ID.
+This request is creating another instance of selected model assigning provided properties as initial values. Those properties are provided as serializable object.
 
 ```javascript
-socket.emit( "<modelName>:create", sessionId, { title: "important things" }, response => {
+socket.emit( "<modelName>:create", { title: "important things" }, response => {
     // - check for `response.success` or `response.error`
     // - process properties of eventually created instance in `response.properties`
     // - created instance's UUID is available as `response.properties.uuid`
@@ -119,7 +121,7 @@ Last argument is a callback to be invoked with the resulting response from serve
 This request is fetching a single instance's properties.
 
 ```javascript
-socket.emit( "<modelName>:read", sessionId, "12345678-1234-1234-1234-123456789012", response => {
+socket.emit( "<modelName>:read", "12345678-1234-1234-1234-123456789012", response => {
     // - check for `response.success` or `response.error`
     // - process properties of fetched instance in `response.properties`
 } );
@@ -129,10 +131,10 @@ Last argument is a callback to be invoked with the resulting response from serve
 
 #### &lt;modelName>:update
 
-This request is updating an existing instance of model. Following the session ID, the UUID of item to update and the values per property to assign are provided in additional arguments.
+This request is updating an existing instance of model. The UUID of item to update and the values per property to assign are provided as arguments.
 
 ```javascript
-socket.emit( "<modelName>:update", sessionId, "12345678-1234-1234-1234-123456789012", { prio: 1 }, response => {
+socket.emit( "<modelName>:update", "12345678-1234-1234-1234-123456789012", { prio: 1 }, response => {
     // - check for `response.success` or `response.error`
     // - properties of updated instance are provided in `response.properties`
 } );
@@ -145,7 +147,7 @@ Last argument is a callback to be invoked with the resulting response from serve
 This request is eventually completing the CRUD-support of this API by deleting an existing instance of model selected by its UUID in first argument.
 
 ```javascript
-socket.emit( "<modelName>:delete", sessionId, "12345678-1234-1234-1234-123456789012", response => {
+socket.emit( "<modelName>:delete", "12345678-1234-1234-1234-123456789012", response => {
     // - check for `response.success` or `response.error`
     // - deleted instance's UUID is available as `response.properties.uuid`
 } );
@@ -156,7 +158,7 @@ Last argument is a callback to be invoked with the resulting response from serve
 
 ### Notifications
 
-[ODM notifications](https://odem.hitchy.org/api/model.html#model-notifications) are forwarded as broadcast events named `<modelName>:changed`. Either event consists of 
+[notifications of the document-oriented database](https://odem.hitchy.org/api/model.html#model-notifications) are forwarded as broadcast events named `<modelName>:changed`. Either event consists of 
 
 - a type of change and 
 - the changed item's properties (limited to its UUID on deletion).