@hitchy/plugin-odem-rest 0.6.0 → 0.7.1

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",

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" );
@@ -23,10 +23,6 @@ module.exports = function() {
 			before.set( `ALL ${resolve( urlPrefix, ".schema" )}`, CORS.getRequestFilterForSchemata() );
 			after.set( `ALL ${resolve( urlPrefix, ".schema" )}`, reqNotSupported );
 
-			if ( api.plugins.authentication ) {
-				before.set( `GET ${resolve( urlPrefix, ".schema" )}`, Services.AuthorizationPolicyGenerator.mayAccess( "@hitchy.odem.schema" ) );
-			}
-
 			for ( let i = 0, numNames = modelNames.length; i < numNames; i++ ) {
 				const name = modelNames[i];
 				const routeName = Case.pascalToKebab( name );
@@ -36,55 +32,6 @@ module.exports = function() {
 				before.set( `ALL ${resolve( urlPrefix, routeName, ".schema" )}`, CORS.getRequestFilterForModelSchema( model ) );
 				before.set( `ALL ${resolve( urlPrefix, routeName, ":uuid" )}`, CORS.getRequestFilterForModelItem( model ) );
 
-				if ( api.plugins.authentication ) {
-					// add policies for additionally checking a requesting user's authorization
-					const modelUrl = resolve( urlPrefix, routeName );
-					const policy = action => Services.AuthorizationPolicyGenerator.mayAccess( `@hitchy.odem.model.${name}.${action}` );
-
-					const handlers = {
-						schema: policy( "schema" ),
-						create: policy( "create" ),
-						list: policy( "list" ),
-						read: policy( "read" ),
-						write: policy( "write" ),
-						check: policy( "check" ),
-						remove: policy( "remove" ),
-					};
-
-					// convenience routes
-					before.set( `GET ${resolve( modelUrl, "create" )}`, handlers.create );
-					before.set( `GET ${resolve( modelUrl, "write", ":uuid" )}`, handlers.write );
-					before.set( `GET ${resolve( modelUrl, "replace", ":uuid" )}`, handlers.write );
-					before.set( `GET ${resolve( modelUrl, "has", ":uuid" )}`, handlers.check );
-					before.set( `GET ${resolve( modelUrl, "remove", ":uuid" )}`, handlers.remove );
-
-					// extended routes
-					before.set( `GET ${resolve( modelUrl, ".schema" )}`, policy( "schema" ) );
-
-					// REST-compliant routes
-					before.set( `GET ${modelUrl}`, function( req, res, next ) {
-						const tail = req.url.substring( modelUrl.length ).trim();
-
-						if ( tail && tail !== "/" ) {
-							next();
-						} else {
-							handlers.list.call( this, req, res, next );
-						}
-					} );
-					before.set( `POST ${resolve( modelUrl )}`, handlers.create );
-					before.set( `GET ${resolve( modelUrl, ":uuid" )}`, ( req, res, next ) => {
-						if ( req.params.uuid === ".schema" ) {
-							next();
-						} else {
-							handlers.read.call( this, req, res, next );
-						}
-					} );
-					before.set( `PATCH ${resolve( modelUrl, ":uuid" )}`, handlers.write );
-					before.set( `PUT ${resolve( modelUrl, ":uuid" )}`, handlers.write );
-					before.set( `HEAD ${resolve( modelUrl, ":uuid" )}`, handlers.check );
-					before.set( `DELETE ${resolve( modelUrl, ":uuid" )}`, handlers.remove );
-				}
-
 				after.set( `ALL ${resolve( urlPrefix, routeName )}`, reqNotSupported );
 			}
 
@@ -123,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() );
@@ -133,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.
 	 *
@@ -143,7 +104,7 @@ module.exports = function() {
 	 * @returns {void}
 	 */
 	function addGlobalRoutes( routes, urlPrefix, models ) {
-		const { runtime: { services: { Model: BaseModel, OdemSchema } }, utility: { case: { pascalToKebab } } } = api;
+		const { services: { Model: BaseModel, OdemSchema }, utility: { case: { pascalToKebab } } } = api;
 
 		routes.set( `GET ${resolve( urlPrefix, ".schema" )}`, reqFetchSchemata );
 
@@ -154,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;
 
@@ -183,11 +149,12 @@ 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 ) {
+	function addRoutesOnModel( routes, urlPrefix, routeName, modelName, Model, includeConvenienceRoutes ) {
 		const { Model: BaseModel, OdemSchema: Schema, OdemUtilityUuid: { ptnUuid } } = Services;
 
 		const modelUrl = resolve( urlPrefix, routeName );
@@ -235,7 +202,7 @@ module.exports = function() {
 		 * @returns {void}
 		 */
 		function reqSuccess( req, res ) {
-			if ( Services.OdemSchema.mayBeExposed( req, Model ) ) {
+			if ( Schema.mayBeExposed( req, Model ) ) {
 				res.status( 200 ).send();
 			} else {
 				res.status( 403 ).send();
@@ -262,14 +229,19 @@ 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.OdemSchema.mayBeExposed( req, Model ) ) {
+			if ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
 				return;
 			}
 
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.schema` ) ) {
+				resAccessForbidden( res );
+				return;
+			}
+
 			res.json( Schema.extractPublicData( Model ) );
 		}
 
@@ -281,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 ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
+			}
+
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.check` ) ) {
+				resAccessForbidden( res );
+				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();
 				} )
@@ -312,25 +289,30 @@ 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 ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
+			}
+
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.read` ) ) {
+				resAccessForbidden( res );
+				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()
+			await item.load()
 				.then( loaded => res.json( Schema.filterItem( loaded.toObject( { serialized: true } ), req, Model, "read" ) ) )
 				.catch( error => {
 					logError( "fetching %s:", routeName, error );
@@ -340,6 +322,7 @@ module.exports = function() {
 							res.status( 404 ).json( { error: "selected item not found" } );
 							break;
 						}
+
 						default : {
 							res.status( 500 ).json( { error: error.message } );
 						}
@@ -355,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 ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
+			}
+
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.list` ) ) {
+				resAccessForbidden( res );
+				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;
@@ -374,7 +362,7 @@ module.exports = function() {
 				handler = reqListMatches;
 			}
 
-			return handler.call( this, req, res );
+			await handler.call( this, req, res );
 		}
 
 		/**
@@ -418,11 +406,6 @@ module.exports = function() {
 		async function reqListMatches( req, res ) {
 			logDebug( "got request listing matching items" );
 
-			if ( !Schema.mayBeExposed( req, Model ) ) {
-				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return;
-			}
-
 			const {
 				q: simpleQuery = "",
 				offset = 0,
@@ -505,17 +488,13 @@ 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;
-			}
-
 			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,
@@ -547,17 +526,22 @@ 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 ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
+			}
+
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.create` ) ) {
+				resAccessForbidden( res );
+				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 ) {
 						if ( record.uuid ) {
@@ -595,23 +579,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 ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
+			}
+
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.write` ) ) {
+				resAccessForbidden( res );
+				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" } );
@@ -655,23 +644,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 ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
+			}
+
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.write` ) ) {
+				resAccessForbidden( res );
+				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 );
@@ -714,23 +708,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 ( !Schema.mayBeExposed( req, Model ) ) {
 				res.status( 403 ).json( { error: "access forbidden by model" } );
-				return undefined;
+				return;
+			}
+
+			if ( api.plugins.authentication && !await Services.Authorization.mayAccess( req.user, `@hitchy.odem.model.${modelName}.remove` ) ) {
+				resAccessForbidden( res );
+				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,7 +1,7 @@
 {
 	"name": "@hitchy/plugin-odem-rest",
-	"version": "0.6.0",
-	"description": "HTTP REST API for Hitchy's ODM",
+	"version": "0.7.1",
+	"description": "HTTP REST API for Hitchy's document-oriented database",
 	"main": "index.js",
 	"scripts": {
 		"lint": "eslint .",
@@ -9,8 +9,7 @@
 	},
 	"repository": "https://gitlab.com/hitchy/plugin-odem-rest.git",
 	"keywords": [
-		"hitchy",
-		"ODM"
+		"hitchy"
 	],
 	"author": "Thomas Urban",
 	"license": "MIT",
@@ -18,7 +17,7 @@
 	"homepage": "https://gitlab.com/hitchy/plugin-odem-rest#plugin-odem-rest",
 	"peerDependencies": {
 		"@hitchy/core": "0.8.x",
-		"@hitchy/plugin-odem": "0.8.x",
+		"@hitchy/plugin-odem": "0.9.x",
 		"@hitchy/plugin-auth": "0.4.x"
 	},
 	"devDependencies": {
@@ -27,8 +26,8 @@
 		"c8": "^10.1.2",
 		"eslint": "^8.57.0",
 		"eslint-config-cepharum": "^1.0.14",
-		"eslint-plugin-promise": "^6.1.1",
-		"mocha": "^10.7.0",
+		"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, temporary in-memory databases and third-party key-value stores.
  
-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
 
@@ -44,7 +44,7 @@ exports.auth = {
 
 > **Do not use this in a production setup!**
 > 
-> This example is granting permissions to create, adjust and remove items of your ODM without any authentication. In addition, all _protected_ models and properties get exposed to everyone.
+> 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!
 
@@ -105,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
@@ -220,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"]}}
@@ -272,7 +272,7 @@ Resources are declared to control authorizations for basically interacting with
   * 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 a more specific resource `@hitchy.odem.schema.model.<ModelName>` isn't revoked from the user.
+  * 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.