update

api/middlewares/checkHeaders.js

@@ -1,23 +1,21 @@
 const conf = require(`${process.env.dirtown}/conf.json`);
-
-const checkHeaders = (req, res, next) => {
   /**
-   * @apiDefine apxHeader
-   * @apiGroup Middleware
-   * @apiDescription Header is mandatory to access apxtrib see tribes/townconf.json.exposedHeaders
-   * A turn around can be done with a simple get params has to be sent in the get url. Usefull to send simple get without header like ?xworkon=tribeName&xlang=en... priority is given to headers
-   * For performance, tokens are store globaly in req.app.locals.tokens={xpaganid:xauth}
-   * if xlang is not in conf.languagesAvailable
+   * @api{get}/CheckHeaders 
+   * @apiGroup Middlewares
+   * @apiName CheckHeaders
+   * @apiDescription a list of header is mandatory to access apxtrib see tribes/townconf.json.exposedHeaders
    *
-   * @apiHeader {string} xjwt Pagans unique jwt token store in local town Pagans data or "noauth"
-   * @apiHeader {string} xpseudo Pagans unique Pagan id in uuid format or "nouuid"
-   * @apiHeader {string} xlang the 2 letter langage it request the api (if not exist the 2 first letter of Accept-Language header ) if lang does not exist in the town then en is set (as it always exist in en).
-   * @apiHeader {string} xtribe Tribes id where pseudo want to act
-   * @apiHeader {string} xapp Name of www/xapp folder that host app that send the request
-   *  /tribeid/person/xpseudo.json have accessright on this app store in /tribe/tribeid/www/xapp
+   * @apiHeader {string} xalias anonymous or unique alias
+   * @apiHeader {string} xapp  name of the webapp store in tribe/tribeid/www/xapp
+   * @apiHeader {string} xlang the 2 letter request langage (if does not exist then return en = english).
+   * @apiHeader {string} xtribe unique tribe name ere xapp exist
+   * @apiHeader {string} xdays a timestamp 0 or generate during the authentifyme process
+   * @apiHeader {string} xhash anonymous or signature of message: xalias_xdays created by alias private key during authentifyme process
+   * @apiHeader {array[]} xprofils list of string profil apply into xtribe for xapp
+   * @apiHeader {string} xuuid a unique number c reated the fisrt time a domain is visited
+   * @apiHeader {integer} xtrkversion a version number link to tracking system
    *
    * @apiError missingexposedHeaders it miss an exposedHeaders
-   *
    * @apiErrorExample {json} Error-Response:
    * 	HTTP/1/1 400 Not Found
    * 		{
@@ -34,7 +32,6 @@ const checkHeaders = (req, res, next) => {
    * 			msg:"tribeiddoesnotexist",
    *      data: {xalias}
    *      }
-   *
    * @apiHeaderExample {json} Header-Exemple:
    *     {
    * 		  xtribe:"apache",
@@ -45,6 +42,7 @@ const checkHeaders = (req, res, next) => {
    *          xapp:"popular"
    * 		}
    */
+const checkHeaders = (req, res, next) => {
   req.session = {};
   const header = {};
   if (!req.header("xlang") && req.header("Content-Language"))

api/middlewares/footer.md

@@ -0,0 +1 @@
+Documentation Best practices

api/middlewares/header.md

@@ -0,0 +1,148 @@
+## api users and backend developers
+
+api documentation for routes and middleware has to respect apidoc's rules [https://apidocjs.com/](https://apidocjs.com) 
+
+To update this doc accessible in [https://wal-ants.ndda.fr/cdn/apidoc](https://wal-ants.ndda.fr/cdn/apidoc) :
+
+`yarn apidoc` 
+
+For api tribe's doc  accessible in [https://smatchit.io/cdn/apidoc](https://smatchit.io/cdn/apidoc) [:](https://smatchit.io/cdn/apidoc:) 
+
+`yarn apidoctribename`
+
+Objects manage in apXtrib: pagans, notifications, nations, towns, tribes, wwws 
+
+All others objects are manage in town/tribe 
+
+persons is the only exception, schema is manage in apXtrib but data are store in a tribe.
+
+apxtrib conf is set in a conf.json at the same folder level:
+
+```plaintext
+/apxtrib/                          # core process 
+/townName_nationName/conf.json     # town settings
+```
+
+url: **/api/routeName** For core api apXtrib in /apxtrib :
+
+```plaintext
+/apxtrib/api/middlewares/
+/apxtrib/api/routes/
+/apxtrib/api/models/
+/apxtrib/api/models/lg/ language customisation for api response
+/apxtrib/api/models/unitest/
+```
+
+url: **/api/smatchit/routeName** for tribe smatchit example api in /town\_nation/tribes/smatchit(tribeid) 
+
+```plaintext
+/town_nation/tribes/smatchit/api/routes/
+/town_nation/tribes/smatchit/api/models/
+/town_nation/tribes/smatchit/api/models/lg/ language  customization 
+```
+
+**static files** are served by nginx, each tribe nginx conf are store and can be customize in /town\_nation/www/nginx\_xtribe\_xapp.conf
+
+object www/websitename are serve with nginx not express.
+
+## Object management (Odmdb)
+
+An object has a name and is defined by a schema that contain properties key.
+
+A propertie has a name and a list of caracteristics (type, pattern,format,...) that have to be validate to be accepted.  
+All properties respect the rules [https://json-schema.org/draft/2020-12/schema,](https://json-schema.org/draft/2020-12/schema,) some extra"format" can be add to mutualise recurrent regex pattern
+
+A checkjson.js is available to manage all specific format [https://wall-ants.ndda.fr/Checkjson.js](https://wall-ants.ndda.fr/Checkjson.js) see **Odmdb - schema Checkjson**
+
+**Additional properties that not exist in 2020-12/schema :**
+
+**required**: an array of required properties
+
+**apxid**: the propertie used as an unique id
+
+**apxuniquekey**: array of unique properties
+
+**apxidx** : array of index
+
+**apxaccessrights**: object with key profilname and accessrights on properties {profilname:{C:\[properties array\],R:\[properties array\],U:\[\],D:\[\]}}
+
+Items of an object are store in files into :  
+
+```plaintext
+/objectnames/idx/keyval_objkey.json
+/objectnames/itm/uniqueid.json
+```
+
+## api pre-request
+
+**Valid header**
+
+A ‘private’ request to pass must contain exposeHeaders from town conf.json
+
+api.exposedHeaders :\["xdays", "xhash", "xalias", "xlang", "xtribe", "xapp", "xuuid" \]
+
+By default for anonymous user:
+
+```plaintext
+{"headers":{
+    "xtrkversion":1,
+    "xtribe":"tribeid ex: smatchit",
+    "xapp":"websitename ex:presentation",
+    "xlang":"fr",
+    "xalias":"anonymous",
+    "xhash":"anonymous",
+    "xdays":0
+  }
+}
+```
+
+App use openpgp.js lib to sign xdays\_xalias with a privatekey and store it in xhash.
+
+/api/middlewares/isAuthenticated.js check if (xhash) is a valid signature of the public key a xhash is valid for 24 hours
+
+See Pagans models that contain authentification process
+
+**api Return can be direct json in case of get without authenntification or an object data**
+
+{status, ref,msg,data}:
+
+*   status: http code return
+*   ref: model/route name reference where message come from
+*   msg: a message template key store into models/lg/name\_lg.json (where lg is 2 letters language)
+*   data: an object data use to render the value of the message key.
+
+## Accessrights:
+
+An alias is just an identity, to access a tribe a person must exist with alias into /town/tribes/tribename/persons/itm/alias.json
+
+A person has a property profils with a list of profilename, common profiles are : pagan (an identity)  / person (an identity with access right in a tribe) / druid (the administrator of a tribe) / major (administrator of a town/server)
+
+Into a tribe you can have many other profil with specifics accessright on tribe's object.
+
+## Add tribe's api:
+
+Accessible with https://dns/api/tribename/routes
+
+```plaintext
+/town/tribes/tribename/api/routes
+/town/tribes/tribename/api/middlewares
+/town/tribes/tribename/api/models
+/town/tribes/tribename/schema
+/town/tribes/tribename/schema/lg
+```
+
+```plaintext
+// Example of a route
+const conf = require(`${process.env.dirtown}/conf.json`);
+const express = require(`${conf.dirapi}/node_modules/express`);
+const fs = require(`${conf.dirapi}/node_modules/fs-extra`);
+const path = require(`${conf.dirapi}/node_modules/path`);
+
+const Nofications = require(`${conf.dirapi}/api/models/Notifications.js`);
+
+// Middlewares
+const checkHeaders = require(`${conf.dirapi}/api/middlewares/checkHeaders`);
+const isAuthenticated = require(`${conf.dirapi}/api/middlewares/isAuthenticated`);
+const Actions = require(`${conf.dirtown}/tribes/smatchit/api/models/Actions`);
+const router = express.Router();
+```

api/middlewares/isAuthenticated.js

@@ -6,24 +6,51 @@ const glob = require("glob");
 const openpgp = require("openpgp");
 
 /**
- *  Check authentification and get person profils for a tribe
- * @param {object} req
- * @param {object} res
- * @param {function} next
- * @returns  {status:}
+ * @api{get}/istauthenticated
+ * @apiGroup Middlewares
+ * @apiName isAUthenticated
+ * @apiDescription Check that exist in town/tmp/tokens/xalias_xdays_xhash.substr(20,200) if not, check the xhash signature with message xalias_xdays come from public key belonging to xalias. If check pass then store a xhash into /tmp/tokens.
+ * A process run each day to clean up all xhas tmp/tokens oldest than 24 hours. 
+ * If authentify it returns header with xprofils store into a person objject -xtribes/person/alias
  *
- * 3 steps:
- * - clean eventual tokens oldest than 24 hours (the first pagan that authenticate of the day will process this)
- * - if token present in /town/tmp/tokens/alias_tribe_part of the xhash return  xprofils with list of profils pagans
- * - if no token then check xhash  with openpgp lib and create one
+ * @apiHeader {string} xalias anonymous or unique alias
+ * @apiHeader {string} xapp  name of the webapp store in tribe/tribeid/www/xapp
+ * @apiHeader {string} xlang the 2 letter request langage (if does not exist then return en = english).
+ * @apiHeader {string} xtribe unique tribe name ere xapp exist
+ * @apiHeader {string} xdays a timestamp 0 or generate during the authentifyme process
+ * @apiHeader {string} xhash anonymous or signature of message: xalias_xdays created by alias private key during authentifyme process
+ * @apiHeader {array[]} xprofils list of string profil apply into xtribe for xapp
+ * @apiHeader {string} xuuid a unique number c reated the fisrt time a domain is visited
+ * @apiHeader {integer} xtrkversion a version number link to tracking system
  *
- * All data related are store in town/tmp/tokens backend, and localstorage headers for front end
- * A penalty function increase a sleep function between 2 fail try of authentification to avoid bruteforce
- */
+ * @apiErrorExample {json} Error-Response:
+ * 	HTTP/1/1 400 Not Found
+ * 		{
+ * 			status:400,
+ * 			ref:"middlewares"
+ * 			msg:"missingheaders",
+ *      data: ["headermissing1"]
+ *      }
+ *@apiErrorExample {json} Error-Response:
+ * 	HTTP/1/1 404 Not Found
+ * 		{
+ * 			status:404,
+ * 			ref:"middlewares"
+ * 			msg:"tribeiddoesnotexist",
+ *      data: {xalias}
+ *      }
+ *
+ * @apiHeaderExample {json} Header-Exemple:
+ *     {
+ * 		  xtribe:"apache",
+ *          xalias:"toto",
+ *          xhash:"",
+ * 		  xdays:"123"
+ *          xlang:"en",
+ *          xapp:"popular"
+ * 		}
+ **/
 const isAuthenticated = async (req, res, next) => {
-  // tokens if valid are store in /dirtown/tmp/tokens/xalias_xdays_xhash(20,200)
-  // once a day rm oldest tokens than 24hours tag job by adding tmp/tokensmenagedone{day}
-
   const withlog = true;
   const currentday = dayjs().date();
   fs.ensureDirSync(`${process.env.dirtown}/tmp/tokens`);
@@ -78,11 +105,6 @@ const isAuthenticated = async (req, res, next) => {
     150 + tmpfs.length - 249
   )}.json`;
 
-  /**
-   *
-   * @param {string} alias   that request an access
-   * @param {string} action  "clean" | "penalty"
-   */
   const bruteforcepenalty = async (alias, action) => {
     const sleep = (ms) => {
       return new Promise((resolve) => setTimeout(resolve, ms));