\n\n \n\n## Installation\n`npm i @byu-oit/ts-claims-engine-middleware`\n\n \n\n## Introduction\nThe Claims Adjudicator Middleware is an _[express](https://expressjs.com)_ middleware function. Its purpose is to make implementing the CAM as convenient as possible to developers already using the express server framework. It is assumed that those reading this already have a knowledge of the Claims Engine -- its use and implementation. To read more about the Claims Engine, visit the [Claims Adjudicator Module GitHub Repo](https://github.com/byu-oit/ts-claims-engine).\n\n \n\n## Usage & Examples\n\n### 1. Define CAM\n```js\n// example/adjudicator.js\nconst {ClaimsAdjudicator, Concept, Relationships} = require('@byu-oit/ts-claims-engine')\n\n// Static subjects for demonstrative purposes.\nconst subjects = {...}\n\nconst concepts = [ // Create concepts\n Concept.Boolean({\n name: 'subject_exists',\n description: 'The subject exists',\n longDescription: 'Determines whether a subject is a known entity within the domain.',\n relationships: [Relationships.EQ, Relationships.NE],\n qualifiers: ['age'],\n async getValue (id, qualifiers) {\n if (qualifiers && qualifiers.age) {\n return subjects[id] !== undefined && subjects[id].age === qualifiers.age\n } else {\n return subjects[id] !== undefined\n }\n }\n }),\n Concept.Number({\n name: 'age',\n description: 'The subject is of age',\n longDescription: 'Determine if the subject is of an age',\n relationships: [Relationships.GT, Relationships.GTE, Relationships.LT, Relationships.LTE, Relationships.EQ, Relationships.NE],\n async getValue (id) {\n return subjects[id].age\n }\n })\n]\n\nmodule.exports = new ClaimsAdjudicator(concepts) // Export adjudicator instance\n```\n\n\n### 2. Define the server with adjudicator middleware\n```js\n// example/server.js\nconst express = require('express')\nconst { middleware, EnforcerError } = require('@byu-oit/ts-claims-engine-middleware')\nconst adjudicator = require('./adjudicator')\n\n;(async function () {\n const app = express()\n\n // REQUIRED: Body parser to handle POST body\n app.use(express.json())\n\n // Log requests as they come in\n app.use((req, res, next) => {\n console.log(req.method + ' ' + req.path)\n return next()\n })\n\n // Implement claims middleware\n const handleClaims = await middleware(adjudicator)\n app.use('/claims', handleClaims)\n\n // Using the enforcer error middleware catches errors made related to the request format\n // If an error occurs that is not related to formatting, a 500 error response will be returned\n app.use(EnforcerError)\n\n // Start server\n const port = process.env.PORT || 8080\n app.listen(port, () => {\n console.log(`Server running on port: ${port}`)\n })\n})()\n```\n \n\n## API\n\n### HTTP Responses\n\nAside from HTTP connection and service errors (e.g., 400 and 500), the CAM will always\nresponse with 200 (Success). The response object must be inspected to determine whether\nthe claim was validated.\n\n### Verification Response Object and Response Codes\n\nA verification response is a JSON object that can be considered an associative array.\nEach property on the object is a verification response object what has two properties.\n\n```json\n {\n \"verified\": true,\n \"metadata\": {\n \"validation_response\": {\n \"code\": 200,\n \"message\": \"Success\"\n }\n }\n }\n```\n\nThe metadata property will always be present and must be inspected to determine whether\nan error occurred.\n\nIf the validation_response code is 200, then the verified property\nwill also be present and its boolean value is the state of the claim.\n\nIf the validation_response code is not 200, then the response will be a single metadata\nobject.\n\nThe CAM returns two errors:\n\n* **400** Bad Request - The claim could not be evaluated because of an error in the \nclaim declaration (e.g., an unrecognized concept or relationship). This error response\nwill include another property in the metadata object `validation_information` which\ngives additional information about what went wrong.\n* **404** Not Found - The subject ID could not be resolved to a resource.\n\n### Endpoints\n\n#### GET /\n\nA GET on the CAM endpoint returns a list of the concept identifiers that can be\nused in claims submitted to this domain.\n\n```json\n {\n \"metadata\": {\n \"validation_response\": {\n \"code\": 200,\n \"message\": \"Success\"\n }\n },\n \"values\": [\n {\n \"id\": \"age\",\n \"type\": \"integer\",\n \"range\": \"0-120\"\n }\n ]\n }\n```\n\nNote: The \"type\" and \"range\" properties are hints. The CAM will simply not\nverify a claim if the reference value is nonsensical.\n\n#### PUT /\n\nA PUT on the CAM endpoint must include a JSON request body that is an associative array\nof one or more independent claims, where the property key is a unique claim identifier\nand the property value is a claim object.\n\n```json\n {\n \"claim1\": \"\",\n \"claim2\": \"\",\n \"claim3\": \"\"\n }\n```\n\nEach claim object takes the following form:\n\n```json\n {\n \"subject\": \"123456789\",\n \"mode\": \"ALL\",\n \"claims\": [\n {\n \"concept\": \"age\",\n \"relationship\": \"gt_or_eq\",\n \"value\": \"21\",\n \"qualifier\": { \"ageOffset\": -5 }\n }\n ]\n }\n```\n\nAn example claim request:\n\n```json\n {\n \"claim_id1\": {\n \"subject\": \"123456789\",\n \"mode\": \"ALL\",\n \"claims\": [\n {\n \"concept\": \"age\",\n \"relationship\": \"gt_or_eq\",\n \"value\": \"21\"\n }\n ]\n },\n \"claim_id2\": {\n \"claim_id\": \"2\",\n \"subject\": \"987654321\",\n \"mode\": \"ALL\",\n \"claims\": [\n {\n \"concept\": \"age\",\n \"relationship\": \"gt_or_eq\",\n \"value\": \"21\"\n }\n ]\n }\n }\n```\n\n#### PUT / Response\n\nThe CAM responds with an associative array where each property's key matches the\nkey given in the request body and each property's value is a claim response\nobject.\n\n```json\n {\n \"claim1\": \"\",\n \"claim2\": \"\",\n \"claim3\": \"\"\n }\n```\n\nEach claim response object takes the following form:\n\n```json\n {\n \"verified\": true,\n \"metadata\": {\n \"validation_response\": {\n \"code\": 200,\n \"message\": \"Success\"\n }\n }\n }\n```\n\nThe \"verified\" property is only present if the validation_response code is 200.\nOtherwise, the validation_response contains error information.\n\nAn example claim response (including both validation states and both error responses):\n\n```json\n\t{\n \"claim_id1\": {\n \"verified\": true,\n \"metadata\": {\n \"validation_response\": {\n \"code\": 200,\n \"message\": \"Success\"\n }\n }\n },\n \"claim_id2\": {\n \"verified\": false,\n \"metadata\": {\n \"validation_response\": {\n \"code\": 200,\n \"message\": \"Success\"\n }\n }\n },\n \"claim_id3\": {\n \"metadata\": {\n \"validation_response\": {\n \"code\": 400,\n \"message\": \"Bad Request\"\n },\n \"validation_information\": [\n \"Relationship gt_or_eq is not defined for concept favorite_food\"\n ]\n }\n },\n \"claim_id4\": {\n \"metadata\": {\n \"validation_response\": {\n \"code\": 404,\n \"message\": \"Not Found\"\n }\n }\n }\n }\n```\n\n## Appendix\n\n### Related Packages\n* **[Claims Adjudicator Module (CAM)](https://github.com/byu-oit/ts-claims-engine)**\n* **[Claims Adjudicator Middleware](https://github.com/byu-oit/ts-claims-engine-middleware)**\n* **[Claims Adjudicator Client](https://github.com/byu-oit/ts-claims-engine-client)**\n* **[Claims Adjudicator WSO2 Request](https://github.com/byu-oit/ts-wso2-claims-request)**\n","readmeFilename":"README.md"}
![\"CI\"](\"https://github.com/byu-oit/ts-claims-engine-middleware/workflows/CI/badge.svg\"){kind=icon}
\n \n \n ![](\"https://codecov.io/gh/byu-oit/ts-claims-engine-middleware/branch/master/graph/badge.svg\"){kind=icon}
\n \n ![\"GitHub](\"https://img.shields.io/github/package-json/v/byu-oit/ts-claims-engine-middleware\")
\n ![\"code](\"https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier\"){kind=icon}
\n