@hitchy/plugin-odem-rest 0.5.6 → 0.7.0

package/api/services/odem-rest/cors.js

@@ -2,7 +2,7 @@
 
 module.exports = function() {
 	const Config = this.config;
-	const Services = this.runtime.services;
+	const Services = this.services;
 
 	const CommonlyAcceptedHeaders = [
 		"Accept", "Accept-Language", "Authorization", "Content-Language",
@@ -28,7 +28,7 @@ module.exports = function() {
 	/**
 	 * Handles CORS-related behaviours.
 	 *
-	 * @name api.runtime.services.OdemRestCors
+	 * @name api.services.OdemRestCors
 	 */
 	class OdemRestCors {
 		/**
@@ -84,7 +84,7 @@ module.exports = function() {
 		static getRequestFilterForModel( model ) { // eslint-disable-line no-unused-vars
 			return ( req, res, next ) => {
 				if ( !res.headersSent ) {
-					if ( Services.OdemRestSchema.mayBeExposed( req, model ) ) {
+					if ( Services.OdemSchema.mayBeExposed( req, model ) ) {
 						this.handleMethods( model, null, req, res, Accepted.model.methods );
 
 						if ( res.hasHeader( "Access-Control-Allow-Origin" ) ) {
@@ -112,7 +112,7 @@ module.exports = function() {
 		static getRequestFilterForModelSchema( model ) { // eslint-disable-line no-unused-vars
 			return ( req, res, next ) => {
 				if ( !res.headersSent ) {
-					if ( Services.OdemRestSchema.mayBeExposed( req, model ) ) {
+					if ( Services.OdemSchema.mayBeExposed( req, model ) ) {
 						this.handleMethods( model, null, req, res, Accepted.schema.methods );
 
 						if ( res.hasHeader( "Access-Control-Allow-Origin" ) ) {
@@ -140,7 +140,7 @@ module.exports = function() {
 		static getRequestFilterForModelItem( model ) { // eslint-disable-line no-unused-vars
 			return ( req, res, next ) => {
 				if ( !res.headersSent && req.params.uuid !== ".schema" ) {
-					if ( Services.OdemRestSchema.mayBeExposed( req, model ) ) {
+					if ( Services.OdemSchema.mayBeExposed( req, model ) ) {
 						this.handleMethods( model, req.params.uuid, req, res, Accepted.item.methods );
 
 						if ( res.hasHeader( "Access-Control-Allow-Origin" ) ) {

package/index.js

@@ -4,7 +4,7 @@ const { posix: { resolve } } = require( "path" );
 
 module.exports = function() {
 	const api = this;
-	const { runtime: { services: Services, models: Models }, utility: { case: Case } } = api;
+	const { services: Services, models: Models, utility: { case: Case } } = api;
 
 	const logDebug = api.log( "hitchy:odem:rest:debug" );
 	const logError = api.log( "hitchy:odem:rest:error" );
@@ -70,7 +70,7 @@ module.exports = function() {
 				const routeName = Case.pascalToKebab( name );
 				const model = Models[name] || {};
 
-				addRoutesOnModel( routes, urlPrefix, routeName, model, convenience );
+				addRoutesOnModel( routes, urlPrefix, routeName, name, model, convenience );
 			}
 
 			routes.set( "HEAD " + resolve( urlPrefix, ":model" ), ( _, res ) => res.status( 404 ).send() );
@@ -80,6 +80,20 @@ module.exports = function() {
 		},
 	};
 
+	/**
+	 * Generates JSON response indicating rejection of access.
+	 *
+	 * @param {Hitchy.Core.ServerResponse} res response manager
+	 * @returns {void}
+	 */
+	function resAccessForbidden( res ) {
+		res
+			.status( 403 )
+			.json( {
+				error: "access forbidden",
+			} );
+	}
+
 	/**
 	 * Adds routes handling common requests not related to particular model.
 	 *
@@ -90,7 +104,7 @@ module.exports = function() {
 	 * @returns {void}
 	 */
 	function addGlobalRoutes( routes, urlPrefix, models ) {
-		const { runtime: { services: { Model: BaseModel, OdemRestSchema } }, utility: { case: { pascalToKebab } } } = api;
+		const { services: { Model: BaseModel, OdemSchema }, utility: { case: { pascalToKebab } } } = api;
 
 		routes.set( `GET ${resolve( urlPrefix, ".schema" )}`, reqFetchSchemata );
 
@@ -101,7 +115,12 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res response manager
 		 * @returns {void}
 		 */
-		function reqFetchSchemata( req, res ) {
+		async function reqFetchSchemata( req, res ) {
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, "@hitchy.odem.schema" ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			const modelKeys = Object.keys( models );
 			const numModels = modelKeys.length;
 
@@ -111,11 +130,11 @@ module.exports = function() {
 				const model = models[modelKeys[i]];
 
 				if ( model.prototype instanceof BaseModel &&
-				     OdemRestSchema.mayBeExposed( req, model ) &&
-				     OdemRestSchema.mayBePromoted( req, model ) ) {
+				     OdemSchema.mayBeExposed( req, model ) &&
+				     OdemSchema.mayBePromoted( req, model ) ) {
 					const slug = pascalToKebab( model.name );
 
-					result[slug] = OdemRestSchema.extractPublicData( model );
+					result[slug] = OdemSchema.extractPublicData( model );
 				}
 			}
 
@@ -130,12 +149,13 @@ module.exports = function() {
 	 *        route patterns into function handling requests matching that pattern
 	 * @param {string} urlPrefix common prefix to use on every route regarding any model-related processing
 	 * @param {string} routeName name of model to be used in path name of request
+	 * @param {string} modelName name of model derived from name extracted from path name of request in `routeName`
 	 * @param {class<Model>} Model model class
 	 * @param {boolean} includeConvenienceRoutes set true to include additional set of routes for controlling all action via GET-requests
 	 * @returns {void}
 	 */
-	function addRoutesOnModel( routes, urlPrefix, routeName, Model, includeConvenienceRoutes ) {
-		const { Model: BaseModel, OdemRestSchema: Schema, OdemUtilityUuid: { ptnUuid } } = Services;
+	function addRoutesOnModel( routes, urlPrefix, routeName, modelName, Model, includeConvenienceRoutes ) {
+		const { Model: BaseModel, OdemSchema: Schema, OdemUtilityUuid: { ptnUuid } } = Services;
 
 		const modelUrl = resolve( urlPrefix, routeName );
 
@@ -182,7 +202,7 @@ module.exports = function() {
 		 * @returns {void}
 		 */
 		function reqSuccess( req, res ) {
-			if ( Services.OdemRestSchema.mayBeExposed( req, Model ) ) {
+			if ( Services.OdemSchema.mayBeExposed( req, Model ) ) {
 				res.status( 200 ).send();
 			} else {
 				res.status( 403 ).send();
@@ -209,10 +229,15 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
 		 * @returns {void}
 		 */
-		function reqFetchSchema( req, res ) {
+		async function reqFetchSchema( req, res ) {
 			logDebug( "got request fetching schema" );
 
-			if ( !Services.OdemRestSchema.mayBeExposed( req, Model ) ) {
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.schema` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
+			if ( !Services.OdemSchema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
 				return;
 			}
@@ -228,23 +253,28 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
 		 * @returns {Promise|undefined} promises request processed successfully
 		 */
-		function reqCheckItem( req, res ) {
+		async function reqCheckItem( req, res ) {
 			logDebug( "got request checking if some item exists" );
 
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.check` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
 			const { uuid } = req.params;
 			if ( !ptnUuid.test( uuid ) ) {
 				res.status( 400 ).send();
-				return undefined;
+				return;
 			}
 
 			const item = new Model( uuid ); // eslint-disable-line new-cap
 
-			return item.$exists
+			await item.$exists
 				.then( exists => {
 					res.status( exists ? 200 : 404 ).send();
 				} )
@@ -259,26 +289,31 @@ module.exports = function() {
 		 *
 		 * @param {Hitchy.Core.IncomingMessage} req description of request
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
-		 * @returns {Promise} promises request processed successfully
+		 * @returns {Promise<void>} promises request processed successfully
 		 */
-		function reqFetchItem( req, res ) {
+		async function reqFetchItem( req, res ) {
 			logDebug( "got request fetching some item" );
 
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.read` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
 			const { uuid } = req.params;
 			if ( !ptnUuid.test( uuid ) ) {
 				res.status( 400 ).json( { error: "invalid UUID" } );
-				return undefined;
+				return;
 			}
 
 			const item = new Model( uuid ); // eslint-disable-line new-cap
 
-			return item.load()
-				.then( loaded => res.json( loaded.toObject( { serialized: true } ) ) )
+			await item.load()
+				.then( loaded => res.json( Schema.filterItem( loaded.toObject( { serialized: true } ), req, Model, "read" ) ) )
 				.catch( error => {
 					logError( "fetching %s:", routeName, error );
 
@@ -287,6 +322,7 @@ module.exports = function() {
 							res.status( 404 ).json( { error: "selected item not found" } );
 							break;
 						}
+
 						default : {
 							res.status( 500 ).json( { error: error.message } );
 						}
@@ -302,17 +338,22 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res response controller
 		 * @returns {Promise} promises response sent
 		 */
-		function reqFetchItems( req, res ) {
+		async function reqFetchItems( req, res ) {
 			logDebug( "got request fetching items" );
 
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.list` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
 			if ( req.headers["x-list-as-array"] ) {
 				res.status( 400 ).json( { error: "fetching items as array is deprecated for security reasons" } );
-				return undefined;
+				return;
 			}
 
 			let handler = reqListAll;
@@ -321,7 +362,7 @@ module.exports = function() {
 				handler = reqListMatches;
 			}
 
-			return handler.call( this, req, res );
+			await handler.call( this, req, res );
 		}
 
 		/**
@@ -332,7 +373,6 @@ module.exports = function() {
 		 */
 		function parseQuery( query ) {
 			const simpleTernary = /^([^:\s]+):between:([^:]+):([^:]+)$/i.exec( query );
-
 			if ( simpleTernary ) {
 				const [ , name, lower, upper ] = simpleTernary;
 
@@ -422,13 +462,13 @@ module.exports = function() {
 
 			const meta = count || req.headers["x-count"] ? {} : null;
 
-			await Model.find( parsedQuery, { offset, limit, sortBy, sortAscendingly: !descending }, {
+			await Model.find( Schema.checkQuery( parsedQuery, req, Model ), { offset, limit, sortBy, sortAscendingly: !descending }, {
 				metaCollector: meta,
 				loadRecords
 			} )
 				.then( matches => {
 					const result = {
-						items: matches.map( m => m.toObject( { serialized: true } ) ),
+						items: matches.map( item => Schema.filterItem( item.toObject( { serialized: true } ), req, Model, "list" ) ),
 					};
 
 					if ( meta ) {
@@ -453,17 +493,18 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
 		 * @returns {Promise|undefined} promises request processed successfully
 		 */
-		function reqListAll( req, res ) {
+		async function reqListAll( req, res ) {
 			logDebug( "got request listing all items" );
 
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
 			const { offset = 0, limit = Infinity, sortBy = null, descending = false, loadRecords = true, count = false } = req.query;
 			const meta = count || req.headers["x-count"] ? {} : null;
-			return Model.list( {
+
+			await Model.list( {
 				offset,
 				limit,
 				sortBy,
@@ -471,7 +512,7 @@ module.exports = function() {
 			}, { loadRecords, metaCollector: meta } )
 				.then( matches => {
 					const result = {
-						items: matches.map( m => m.toObject( { serialized: true } ) ),
+						items: matches.map( item => Schema.filterItem( item.toObject( { serialized: true } ), req, Model, "list" ) ),
 					};
 
 					if ( meta ) {
@@ -495,38 +536,37 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
 		 * @returns {Promise|undefined} promises request processed successfully
 		 */
-		function reqCreateItem( req, res ) {
+		async function reqCreateItem( req, res ) {
 			logDebug( "got request creating item" );
 
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.create` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
 			const item = new Model(); // eslint-disable-line new-cap
 
-			return ( req.method === "GET" ? Promise.resolve( req.query ) : req.fetchBody() )
+			await ( req.method === "GET" ? Promise.resolve( req.query ) : req.fetchBody() )
 				.then( record => {
-					if ( record.uuid ) {
-						logDebug( "creating %s:", routeName, "new entry can not be created with uuid" );
-						res.status( 400 ).json( { error: "new entry can not be created with uuid" } );
-						return undefined;
-					}
-
 					if ( record ) {
-						const names = Object.keys( record );
-						const numNames = names.length;
+						if ( record.uuid ) {
+							logDebug( "creating %s:", routeName, "new entry can not be created with uuid" );
+							res.status( 400 ).json( { error: "new entry can not be created with uuid" } );
+							return undefined;
+						}
 
+						const filtered = Schema.filterItem( record, req, Model, "create" );
 						const definedProps = Model.schema.props;
 						const definedComputed = Model.schema.computed;
 
-						for ( let i = 0; i < numNames; i++ ) {
-							const name = names[i];
-
-							if ( definedProps[name] ) {
-								item.$properties[name] = record[name];
-							} else if ( definedComputed[name] ) {
-								item[name] = record[name];
+						for ( const [ key, value ] of Object.entries( filtered ) ) {
+							if ( definedProps[key]?.$type || definedComputed[key] ) {
+								item[key] = value;
 							}
 						}
 					}
@@ -549,23 +589,28 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
 		 * @returns {Promise|undefined} promises request processed successfully
 		 */
-		function reqModifyItem( req, res ) {
+		async function reqModifyItem( req, res ) {
 			logDebug( "got request to modify some item" );
 
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.write` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
 			const { uuid } = req.params;
 			if ( !ptnUuid.test( uuid ) ) {
 				res.status( 400 ).json( { error: "invalid UUID" } );
-				return undefined;
+				return;
 			}
 
 			const item = new Model( uuid ); // eslint-disable-line new-cap
 
-			return item.$exists
+			await item.$exists
 				.then( exists => {
 					if ( !exists ) {
 						res.status( 404 ).json( { error: "selected item not found" } );
@@ -578,27 +623,20 @@ module.exports = function() {
 					] )
 						.then( ( [ loaded, record ] ) => {
 							if ( record ) {
-								// FIXME consider using Odem's Model.fromObject() method here
-								const names = Object.keys( record );
-								const numNames = names.length;
-
+								const filtered = Schema.filterItem( record, req, Model, "write" );
 								const definedProps = Model.schema.props;
 								const definedComputed = Model.schema.computed;
 
-								for ( let i = 0; i < numNames; i++ ) {
-									const name = names[i];
-
-									if ( definedProps[name] ) {
-										loaded.$properties[name] = record[name]; // eslint-disable-line no-param-reassign
-									} else if ( definedComputed[name] ) {
-										loaded[name] = record[name]; // eslint-disable-line no-param-reassign
+								for ( const [ key, value ] of Object.entries( filtered ) ) {
+									if ( definedProps[key]?.$type || definedComputed[key] ) {
+										loaded[key] = value; // eslint-disable-line no-param-reassign
 									}
 								}
 							}
 
 							return loaded.save()
 								.then( saved => {
-									res.json( saved.toObject( { serialized: true } ) );
+									res.json( Schema.filterItem( saved.toObject( { serialized: true } ), req, Model, "read" ) );
 								} );
 						} );
 				} )
@@ -616,23 +654,28 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
 		 * @returns {Promise|undefined} promises request processed successfully
 		 */
-		function reqReplaceItem( req, res ) {
+		async function reqReplaceItem( req, res ) {
 			logDebug( "got request replacing some item" );
 
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.write` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
 			const { uuid } = req.params;
 			if ( !ptnUuid.test( uuid ) ) {
 				res.status( 400 ).json( { error: "invalid UUID" } );
-				return undefined;
+				return;
 			}
 
 			const item = new Model( uuid, { onUnsaved: false } ); // eslint-disable-line new-cap
 
-			return Promise.all( [ item.$exists, req.method === "GET" ? Promise.resolve( req.query ) : req.fetchBody() ] )
+			await Promise.all( [ item.$exists, req.method === "GET" ? Promise.resolve( req.query ) : req.fetchBody() ] )
 				.then( ( [ exists, record ] ) => {
 					return ( exists ? item.load() : Promise.resolve() ).then( () => {
 						const propNames = Object.keys( Model.schema.props );
@@ -640,30 +683,27 @@ module.exports = function() {
 
 						const computedNames = Object.keys( Model.schema.computed );
 						const numComputedNames = computedNames.length;
+						const filtered = Schema.filterItem( record, req, Model, "write" );
 
 						// update properties, drop those missing in provided record
 						for ( let i = 0; i < numPropNames; i++ ) {
 							const propName = propNames[i];
-							const value = record[propName];
+							const value = filtered[propName];
 
-							if ( value == null ) {
-								item.$properties[propName] = null;
-							} else {
-								item.$properties[propName] = value;
-							}
+							item[propName] = value ?? null;
 						}
 
 						// assign all posted computed properties
 						for ( let i = 0; i < numComputedNames; i++ ) {
 							const computedName = computedNames[i];
-							item[computedName] = record[computedName];
+							item[computedName] = filtered[computedName];
 						}
 
 						return item.save( { ignoreUnloaded: !exists } );
 					} );
 				} )
 				.then( saved => {
-					res.json( { uuid: saved.uuid } );
+					res.json( Schema.filterItem( saved.toObject( { serialized: true } ), req, Model, "read" ) );
 				} )
 				.catch( error => {
 					logError( "updating %s:", routeName, error );
@@ -678,23 +718,28 @@ module.exports = function() {
 		 * @param {Hitchy.Core.ServerResponse} res API for creating response
 		 * @returns {Promise|undefined} promises request processed successfully
 		 */
-		function reqRemoveItem( req, res ) {
+		async function reqRemoveItem( req, res ) {
 			logDebug( "got request removing some item" );
 
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.remove` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
 			}
 
 			const { uuid } = req.params;
 			if ( !ptnUuid.test( uuid ) ) {
 				res.status( 400 ).json( { error: "invalid UUID" } );
-				return undefined;
+				return;
 			}
 
 			const item = new Model( uuid ); // eslint-disable-line new-cap
 
-			return item.$exists
+			await item.$exists
 				.then( exists => {
 					if ( exists ) {
 						return item.remove()

package/package.json

@@ -1,34 +1,33 @@
 {
 	"name": "@hitchy/plugin-odem-rest",
-	"version": "0.5.6",
-	"description": "HTTP REST API for Hitchy's ODM",
+	"version": "0.7.0",
+	"description": "HTTP REST API for Hitchy's document-oriented database",
 	"main": "index.js",
 	"scripts": {
 		"lint": "eslint .",
-		"test": "hitchy-pm odem --exec mocha --ui=tdd 'test/scripts/**/*.js'",
-		"coverage": "hitchy-pm odem --exec c8 mocha --ui=tdd 'test/scripts/**/*.js'"
+		"test": "hitchy-pm odem auth --exec c8 mocha --ui=tdd 'test/scripts/**/*.js'"
 	},
 	"repository": "https://gitlab.com/hitchy/plugin-odem-rest.git",
 	"keywords": [
-		"hitchy",
-		"ODM"
+		"hitchy"
 	],
 	"author": "Thomas Urban",
 	"license": "MIT",
 	"bugs": "https://gitlab.com/hitchy/plugin-odem-rest/-/issues",
 	"homepage": "https://gitlab.com/hitchy/plugin-odem-rest#plugin-odem-rest",
 	"peerDependencies": {
-		"@hitchy/core": "^0.8.x",
-		"@hitchy/plugin-odem": "^0.7.8"
+		"@hitchy/core": "0.8.x",
+		"@hitchy/plugin-odem": "0.9.x",
+		"@hitchy/plugin-auth": "0.4.x"
 	},
 	"devDependencies": {
 		"@hitchy/types": "^0.1.3",
-		"@hitchy/server-dev-tools": "^0.4.8",
-		"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": "^6.6.0",
+		"mocha": "^10.7.3",
 		"should": "^13.2.3",
 		"should-http": "^0.1.1"
 	}

package/readme.md

@@ -1,10 +1,10 @@
 # plugin-odem-rest [![pipeline status](https://gitlab.com/hitchy/plugin-odem-rest/badges/master/pipeline.svg)](https://gitlab.com/hitchy/plugin-odem-rest/-/commits/master)
 
-HTTP REST API for [Hitchy's](https://core.hitchy.org/) [ODM](https://odem.hitchy.org/)
+HTTP REST API for [Hitchy's](https://core.hitchy.org/) [document-oriented database](https://odem.hitchy.org/)
 
-[Hitchy](http://core.hitchy.org/) is a server-side framework for developing web applications with [Node.js](https://nodejs.org/). [Odem](https://www.npmjs.com/package/@hitchy/plugin-odem) is plugin for Hitchy implementing an object document management (ODM) using data backends like regular file systems, LevelDBs and temporary in-memory databases.
+[Hitchy](http://core.hitchy.org/) is a server-side framework for developing web applications with [Node.js](https://nodejs.org/). [Odem](https://www.npmjs.com/package/@hitchy/plugin-odem) is a plugin for Hitchy implementing a document-oriented database using data backends like regular file systems, LevelDBs and temporary in-memory databases.
  
-This plugin is defining blueprint routes for accessing data managed in ODM using REST API.
+This plugin is defining blueprint routes for accessing data managed in document-oriented database using REST API.
 
 ## License
 
@@ -21,15 +21,34 @@ npm i @hitchy/plugin-odem-rest @hitchy/plugin-odem
 The command is installing this plugin and the additionally required [@hitchy/plugin-odem](https://www.npmjs.com/package/@hitchy/plugin-odem). 
 
 :::warning Compatibility  
-Starting with version 0.4.0 the latter plugin must be installed 
-explicitly.  
-::: 
+Starting with version 0.4.0 the latter plugin must be installed explicitly.  
+:::
+
+:::warning Compatibility  
+Starting with version 0.6.0 authorization is tightened as soon as [@hitchy/plugin-auth](https://auth.hitchy.org) is discovered in current project. You need an [additional configuration](#authorization) to keep the REST API as open as before.  
+:::
 
 ## Usage
 
 This package depends on [@hitchy/plugin-odem](https://odem.hitchy.org/) and its preparation of model definitions discovered by [Hitchy's core](https://core.hitchy.org/). See the linked manuals for additional information.
 
-For a quick start example create a file **api/models/local-employee.js** in your Hitchy-based application with the following content:
+In addition, [@hitchy/plugin-auth](https://auth.hitchy.org) is supported resulting in a tightened access control. When using that plugin in a project, a file **config/auth.js** with following content is necessary to test-drive this plugin's REST API:
+
+```javascript
+exports.auth = {
+    authorizations: {
+        "@hitchy.odem": "*"
+    }
+};
+```
+
+> **Do not use this in a production setup!**
+> 
+> This example is granting permissions to create, adjust and remove items of your document-oriented database without any authentication. In addition, all _protected_ models and properties get exposed to everyone.
+> 
+> See the [section on authorization](#authorization) for additional information!
+
+Now, for a quick start example create a file **api/models/local-employee.js** in your Hitchy-based application with the following content:
 
 ```javascript
 module.exports = {
@@ -60,7 +79,7 @@ module.exports = {
 };
 ```
 
-When starting your Hitchy-based application it will discover a model named **LocalEmployee** and expose it via REST API using URLs like `/api/local-employee` just because of this package and its dependencies mentioned before.
+When starting your Hitchy-based application it will discover a model named **LocalEmployee** and expose it via REST API using base URL `/api/local-employee` just because of this package and its dependencies mentioned before.
 
 #### Models of Hitchy plugins
 
@@ -69,7 +88,7 @@ Due to the way Hitchy is discovering plugins and compiling [components](https://
 
 ### How it works
 
-This plugin is defining a set of [blueprint routes](https://core.hitchy.org/internals/routing-basics.html#focusing-on-routes) implementing REST API for every model defined in file system as described before.
+This plugin is defining a set of [blueprint routes](https://core.hitchy.org/internals/routing-basics.html#focusing-on-routes) implementing a REST API for every model defined in file system as described before.
 
 Those routes comply with this pattern:
 
@@ -86,7 +105,7 @@ exports.model = {
 
 The model's segment in URL `<model>` is derived as the kebab-case version of model's name which is given in PascalCase. Thus, a model definition in a file named **api/models/my-fancy-model.js** is assumed to describe a model named **MyFancyModel** by default, resulting in model's URL segment to be **my-fancy-model** again. So the URL path for the collection of items is `/api/my-fancy-model`.
 
-In Hitchy's ODM all model instances or items are uniquely addressable via UUIDs. By appending an item's UUID to the given URL path of a collection you get the URL path of that item, e.g. `/api/my-fancy-model/01234567-1234-1234-1234-56789abcdef0`.
+In Hitchy's document-oriented database all model instances or items are uniquely addressable via UUIDs. By appending an item's UUID to the given URL path of a collection you get the URL path of that item, e.g. `/api/my-fancy-model/01234567-1234-1234-1234-56789abcdef0`.
 
 
 ### The REST API
@@ -201,9 +220,9 @@ For example, a GET-request for `/api/localEmployee?q=salary:between:2000:4000` w
 
 ##### Complex tests <Bade type=info text=v0.5.2+></Badge>
 
-Hitchy ODM supports more complex queries that can't be encoded as such simple queries as described above. Thus, a different way of querying has been added. 
+Hitchy's document-oriented database supports more complex queries that can't be encoded as such simple queries as described above. Thus, a different way of querying has been added. 
 
-When using parameter `query` instead of `q`, its value is assumed to be a JSON-encoded query complying with query syntax supported by [Model.find() method of Hitchy ODM](https://odem.hitchy.org/api/model.html#model-find).
+When using parameter `query` instead of `q`, its value is assumed to be a JSON-encoded query complying with query syntax supported by [Model.find() method of Hitchy's document-oriented database](https://odem.hitchy.org/api/model.html#model-find).
 
 ```http request
 GET /api/user?query={"in":{"name":["john","jane","jason"]}}
@@ -231,3 +250,73 @@ Using query parameter `sortBy=lastName` a fetched list of items is sorted by val
 Query parameter `limit=n` is requesting to fetch at most **n** items. Parameter `offset=n` is requesting to skip **n** items before starting retrieval. Slicing is applied after sorting items.
 
 When slicing this way only a subset of basically available items is fetched by intention. If you need to know the total number of available items when requesting a slice you can either set custom field `x-count` in request header or query parameter `count` to `1` or any other truthy value. This will have a slight negative impact on request performance, but causes delivery of the total number of matching items in a separate property `count` of response body as well as in response header named `x-count`.
+
+#### Authorization
+
+As soon as [@hitchy/plugin-auth](https://auth.hitchy.org) is included with your project, **@hitchy/plugin-odem-rest** is using it to check a requesting user's authorization by declaring named [resources](https://auth.hitchy.org/introduction.html#resources) available for setting up authorization rules in [database](https://auth.hitchy.org/api/model/authorization-rule.html) or in [configuration](https://auth.hitchy.org/api/config.html#config-auth-authorizations).
+
+##### Resource namespace
+
+All declared resources share common prefix `@hitchy.odem`.
+
+Despite the generic name, the authorization control described here does not apply to **@hitchy/plugin-odem** in general. Custom server-side code needs to stay capable of interacting with models and their private or protected properties. Instead, authorization control affects the REST API implemented by this plugin, only. Other plugins may implement APIs for accessing the same models by different means. Those plugins may share the resource naming pattern described here so that all APIs featuring remote interaction with the data can be controlled in the same way. Thus, resource names omit to refer to the REST API explicitly. 
+
+##### Per-model resources
+
+Resources are declared to control authorizations for basically interacting with either model:
+
+  * When finding or listing items, accessing the resource `@hitchy.odem.model.<ModelName>.list` must be granted.
+  * When checking an item, accessing the resource `@hitchy.odem.model.<ModelName>.check` must be granted.
+  * When reading an item, accessing the resource `@hitchy.odem.model.<ModelName>.read` must be granted.
+  * When patching or replacing an item, accessing the resource `@hitchy.odem.model.<ModelName>.write` must be granted.
+  * When creating a new item, accessing the resource `@hitchy.odem.model.<ModelName>.create` must be granted.
+  * When removing an item, accessing the resource `@hitchy.odem.model.<ModelName>.remove` must be granted.
+  * Accessing a model's schema requires the resource `@hitchy.odem.model.<ModelName>.schema` to be granted.
+  * Accessing the collection of all models' schemata requires the resource `@hitchy.odem.schema` to be granted. This implicitly causes models with their [promote option](https://odem.hitchy.org/guides/defining-models.html#options) being `protected` to be exposed in responses to that request unless resource `@hitchy.odem.model.<ModelName>.promote` isn't revoked from the user.
+
+> In these examples, replace `<ModelName>` with a model's name in PascalCase.
+
+##### Per-property resources
+
+In addition, resources are declared to control access on a model's protected properties. By default, protected properties are hidden from a user's REST request.
+
+> Prior to supporting **@hitchy/plugin-auth** for authoriation control in v0.6.0, protected properties have been available to any authenticated user. The same behavior still applies if **@hitchy/plugin-auth** isn't available in a project.
+
+  * When finding or listing items, accessing the resource `@hitchy.odem.model.<ModelName>.property.<propertyName>.list` must be granted for the protected property to be supported in filter queries and to include it in resulting set of items.
+  * When reading an item, accessing the resource `@hitchy.odem.model.<ModelName>.property.<propertyName>.read` must be granted to include the property in the resulting record.
+  * When creating an item, accessing the resource `@hitchy.odem.model.<ModelName>.property.<propertyName>.create` must be granted to include the property in the resulting record.
+  * When patching or replacing an item, accessing the resource `@hitchy.odem.model.<ModelName>.property.<propertyName>.write` must be granted to consider an update for the property and to include it in the resulting record.
+
+> In these examples, replace `<ModelName>` with a model's name in PascalCase and `<propertyName>` with its name as defined in the model.
+
+Per-property authorization control is not considered for public and private properties. This is meant to limit performance penalties on processing requests. 
+
+  * Public properties are always available via REST API as soon as the according [per-model authorization](#per-model-resources) is given.
+  * Private properties are never available.
+
+##### Examples
+
+The following example for a file **config/auth.js** is effectively disabling all authorization control in context of **@hitchy/plugin-odem-rest** and thus should be used for evaluation purposes, only:
+
+```javascript
+exports.auth = {
+    authorizations: {
+        "@hitchy.odem": "*"
+    }
+};
+```
+
+A slightly more sophisticated example could look like this:
+
+```javascript
+exports.auth = {
+    authorizations: {
+        "@hitchy.odem": "*",
+        "@hitchy.odem.model.User": [ "-*", "@admin" ],
+        "@hitchy.odem.model.Role": [ "-*", "@admin" ],
+        "@hitchy.odem.model.User.property.password": [ "-*" ],
+    }
+};
+```
+
+This example is granting access to all features of **@hitchy/plugin-odem-rest** unless they address either model `User` or `Role`. Access on those models is limited to users with role `admin`. However, even those users must not access protected property `password`, though you might want to declare it as private anyway in which case last rule in given example does not have any effect.

package/api/services/odem-rest/schema.js

@@ -1,208 +0,0 @@
-"use strict";
-
-const PtnAcceptsValue = /^\s*(?:function\s*(?:\s\S+\s*)?)?\(\s*[^\s)]/;
-
-module.exports = function() {
-	/**
-	 * Handles model schemata in context of REST-API plugin.
-	 *
-	 * @name api.runtime.services.OdemRestSchema
-	 */
-	class OdemRestSchema {
-		/**
-		 * Detects if selected model's schema may be promoted to clients or not.
-		 *
-		 * @param {HitchyIncomingMessage} request request descriptor
-		 * @param {class<Model>} model class of model to check
-		 * @returns {boolean} true if model's schema may be promoted to clients, false otherwise
-		 */
-		static mayBePromoted( request, model ) {
-			const { schema: { options } } = model;
-
-			const scope = String( options.promote || options.expose || "public" ).trim().toLowerCase();
-
-			switch ( scope ) {
-				case "public" :
-					return true;
-
-				case "protected" :
-					return Boolean( request.user );
-
-				default :
-					return false;
-			}
-		}
-
-		/**
-		 * Detects if selected model may be exposed to clients or not.
-		 *
-		 * @param {HitchyIncomingMessage} request request descriptor
-		 * @param {class<Model>} model class of model to check
-		 * @returns {boolean} true if model may be exposed to clients, false otherwise
-		 */
-		static mayBeExposed( request, model ) {
-			const { schema: { options } } = model;
-
-			const scope = String( options.expose || "public" ).trim().toLowerCase();
-
-			switch ( scope ) {
-				case "public" :
-					return true;
-
-				case "protected" :
-					return Boolean( request.user );
-
-				default :
-					return false;
-			}
-		}
-
-		/**
-		 * Extracts information on selected model's schema for publishing.
-		 *
-		 * @param {class<Model>} model model to process
-		 * @param {boolean} omitComputed set true to omit computed properties
-		 * @returns {object} extracted public information on selected model's schema
-		 */
-		static extractPublicData( model, { omitComputed = false } = {} ) {
-			const { schema: { props, computed, options } } = model;
-
-			const extracted = {
-				name: model.name,
-				props: {},
-			};
-
-			const propNames = Object.keys( props );
-			const numProps = propNames.length;
-
-			for ( let i = 0; i < numProps; i++ ) {
-				const name = propNames[i];
-				const prop = props[name];
-
-				const copy = extracted.props[name] = {
-					type: prop.type || "string",
-				};
-
-				const optionNames = Object.keys( prop );
-				const numOptions = optionNames.length;
-
-				for ( let j = 0; j < numOptions; j++ ) {
-					const optionName = optionNames[j];
-
-					switch ( optionName.toLowerCase() ) {
-						case "type" :
-						case "indexes" :
-						case "indices" :
-						case "index" :
-							break;
-
-						default : {
-							const option = prop[optionName];
-
-							if ( option != null && typeof option !== "function" ) {
-								copy[optionName] = this.cloneSerializable( option );
-							}
-						}
-					}
-				}
-			}
-
-			if ( !omitComputed ) {
-				const computedNames = Object.keys( props );
-				const numComputed = computedNames.length;
-				extracted.computed = {};
-
-				for ( let i = 0; i < numComputed; i++ ) {
-					const name = computedNames[i];
-					const fn = computed[name];
-
-					if ( typeof fn === "function" ) {
-						extracted.computed[name] = PtnAcceptsValue.test( fn );
-					}
-				}
-			}
-
-			const optionsNames = Object.keys( options );
-			const numOptions = optionsNames.length;
-
-			for ( let i = 0; i < numOptions; i++ ) {
-				const name = optionsNames[i];
-
-				switch ( name ) {
-					case "onUnsaved" :
-					case "expose" :
-					case "promote" :
-						break;
-
-					default : {
-						if ( !extracted.options ) {
-							extracted.options = {};
-						}
-
-						const option = options[name];
-
-						if ( option != null && typeof option !== "function" ) {
-							extracted.options[name] = this.cloneSerializable( option );
-						}
-					}
-				}
-			}
-
-			return extracted;
-		}
-
-		/**
-		 * Creates deep clone of provided value omitting any data can't be or
-		 * mustn't be serialized.
-		 *
-		 * @param {*} input data to be cloned
-		 * @returns {*} (partial) clone of provided data
-		 */
-		static cloneSerializable( input ) {
-			switch ( typeof input ) {
-				case "object" : {
-					if ( Array.isArray( input ) ) {
-						const numItems = input.length;
-						const clone = new Array( numItems );
-						let write = 0;
-
-						for ( let read = 0; read < numItems; read++ ) {
-							const value = this.cloneSerializable( input[read] );
-
-							if ( value != null ) {
-								clone[write++] = value;
-							}
-						}
-
-						clone.splice( write );
-
-						return clone;
-					}
-
-					const names = Object.keys( input );
-					const numNames = names.length;
-					const clone = {};
-
-					for ( let i = 0; i < numNames; i++ ) {
-						const name = names[i];
-						const value = this.cloneSerializable( input[name] );
-
-						if ( value != null ) {
-							clone[name] = value;
-						}
-					}
-
-					return clone;
-				}
-
-				case "function" :
-					return null;
-
-				default :
-					return input;
-			}
-		}
-	}
-
-	return OdemRestSchema;
-};