{"id":20671119,"url":"https://github.com/allnulled/mysql-auth","last_synced_at":"2026-04-20T12:04:43.186Z","repository":{"id":57306782,"uuid":"248842929","full_name":"allnulled/mysql-auth","owner":"allnulled","description":"Auth system for MySQL and Node.js: users, communities and privileges","archived":false,"fork":false,"pushed_at":"2020-08-20T17:14:09.000Z","size":1060,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-17T21:56:08.808Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://npmjs.com/mysql-auth","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/allnulled.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-20T20:09:58.000Z","updated_at":"2020-04-26T10:53:43.000Z","dependencies_parsed_at":"2022-08-31T01:12:34.143Z","dependency_job_id":null,"html_url":"https://github.com/allnulled/mysql-auth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fmysql-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fmysql-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fmysql-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fmysql-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allnulled","download_url":"https://codeload.github.com/allnulled/mysql-auth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242889623,"owners_count":20201992,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T20:25:11.809Z","updated_at":"2026-04-20T12:04:43.158Z","avatar_url":"https://github.com/allnulled.png","language":"JavaScript","readme":"# mysql-auth\n\nAuthentication and authorization system for MySQL and Node.js: users, communities and privileges.\n\n## Installation\n\n`$ npm i -g mysql-auth`\n\n## Why?\n\nThis tool is a little framework for `authentication` and `authorization` management based in `mysql` and `node.js` mainly.\n\nThe reason was to create a tool to universally manage these topics of any kind of application in a comfortable, relaxed way.\n\n## Features\n\nThese are some of the advantages of `mysql-auth`:\n\n   - [✔] Comfortable object-oriented API for `authentication` and `authorization`\n   - [✔] Fully based in `Promises`\n   - [✔] Manages `users`, `communities` and `privileges`\n   - [✔] Manages `privileges` per `user` and per `community`\n   - [✔] Manages `sessions` too\n   - [✔] Creates the basic tables too, by API or CLI\n   - [✔] Deletes all the related tables easily too, by API or CLI\n   - [✔] Easily hookable and extendable API\n   - [✔] Query sanitization in every input\n   - [✔] Builds queries using `ejs` templating system\n   - [✔] Caches the most queried table `session`\n   - [✔] Flexible parametrization of API\n   - [✔] Historical data automatically stored in different[ly prefixed] tables\n   - [✔] There is not an enterprise version of this software\n   - [✔] Free license [(WTFPL)](https://es.wikipedia.org/wiki/WTFPL)\n\n### Additional details\n\n   - [✔] Unconfirmed users are not true users\n   - [✔] History tables are created and updated automatically for you, too\n   - [✔] User's `name` and `email` must be unique\n   - [✔] User's `password` is automatically encrypted and never decrypted\n   - [✔] Sessions autogenerate their `token` and `secret_token`\n   - [✔] Cache is refreshed only when required\n   - [✔] Cache is an in-memory map\n   - [✔] Database connection is made by a pool of connections (and it must be closed manually from API)\n\n## Usage\n\n### CLI usage\n\n*Note: CLI is only to create and delete the tables that will manage the auth*\n\n```sh\nmysql-auth \n   --command create     # or \u003cdelete\u003e\n   --host 127.0.0.1     # db host\n   --port 3306          # db port\n   --database test      # db name\n   --user test          # db user\n   --password test      # db password\n```\n\n### API usage\n\n##### Initialize a client\n\n```js\nconst MySQLAuthSystem = require(\"mysql-auth\");\n\nconst auth = MySQLAuthSystem.create({\n   connectionSettings: {\n      host: ...,\n      port: ...,\n      database: ...,\n      user: ...,\n      password: ...,\n   },\n   debug: true, // this will log all SQL queries made by the framework\n   trace: false // this will log by console everytime a method of the API is called\n});\n```\n\n##### Play with the API\n\n```js\nawait auth.registerUnconfirmedUser({ name: \"user1\", password: \"1\", email: \"user1@email.com\" });\nawait auth.confirmUser({ name: \"user1\" });\nconst { data } = await auth.login({ name: \"user1\", password: \"1\" });\nawait auth.assignPrivilegeToUser({ name: \"speak\" }, { name: \"user1\" });\nawait auth.assignCommunityToUser({ name: \"community 1\" }, { name: \"user1\" });\nawait auth.assignPrivilegeToCommunity({ name: \"vote\" }, { name: \"humans\" });\n// ...\n```\n\n\n\n## Overview and philosophy\n\nYou have a basic set of onthologies in your database.\n\nThese onthologies will manage, strictly, the core of an authentication and authorization basic system.\n\n### Prefixes\n\nThese onthologies are namespaced with a fixed prefix: `$auth$`.\n\n### Historical data\n\nThese onthologies also have its correlative **history table** (which is automatically synchronized by the API).\n\nThe historical tables are namespaced with a fixed prefix: `$hist$$auth$`.\n\nUnder the hood, we are using the `mysql-history` library.\n\nThis library, `mysql-history` formats (again, prefixes) all its tables like:\n\n  - `$hist${{ name of the target table }}`\n\n### Primary onthologies\n\nThese are the primary tables of the auth system:\n\n   - **user** (`$auth$user`)\n   - **unconfirmed_user** (`$auth$unconfirmed_user`)\n   - **community** (`$auth$community`)\n   - **privilege** (`$auth$privilege`)\n   - **session** (`$auth$session`)\n\n### Connector onthologies\n\nThese are the connector tables of the auth system:\n\n   - **user and community** (`$auth$user_and_community`): each row tells that **X user belongs to Y community**\n   - **user and privilege** (`$auth$user_and_privilege`): each row tells that **X user has Y privilege**\n   - **community and privilege** (`$auth$community_and_privilege`): each row tells that **X community has Y privilege**\n\n### Properties of: user, community and privilege\n\nAll primary onthologies share these properties:\n\n   - **id** (always **primary key**)\n   - **name** (always **unique**)\n   - **description**\n   - **created at**\n   - **updated at**\n\n### Properties of: user\n\nThese properties are specific of the tables **user** and **unconfirmed user**:\n\n   - **password** (automatically **encrypted**)\n   - **email** (**unique**)\n\n### Properties of: session\n\nThese properties are specific of the table **session**:\n\n   - **token**\n   - **secret token**\n   - **data**\n\n### The creational script \n\nThe script that creates the tables is here:\n\n[`https://github.com/allnulled/mysql-auth/blob/master/src/queries/create tables.sql.ejs`](https://github.com/allnulled/mysql-auth/blob/master/src/queries/create%20tables.sql.ejs)\n\n\n## API Reference\n\nThe API represents the set of classes, methods, and their signatures.\n\nThis contracts in the input and output of these functions are the core API that is left to the developer to implement,\non this own way, the API.\n\n### API methods list\n\n```js\nAuth = require(\"mysql-auth\");\nauth = Auth.create({\n   connectionSettings: {\n      host: \"127.0.0.1\",\n      port: 3306,\n      database: \"test\",\n      user: \"test\",\n      password: \"test\"\n   },\n   debug: false,\n   trace: false,\n})\nauth.assignPrivilegeToUser(wherePrivilege, whereUser)\nauth.assignUserToCommunity(whereUser, whereCommunity)\nauth.authenticate(whereSession, settings)\nauth.can(token, privilege, defaultPolicy)\nauth.canMultiple(token, canArgsList)\nauth.cannot(token, privilege, defaultPolicy)\nauth.cannotMultiple(token, canArgsList)\nauth.confirmUser(user)\nauth.createTables()\nauth.deleteCommunity(whereCommunity)\nauth.deletePrivilege(wherePrivilege)\nauth.deleteTables()\nauth.deleteUnconfirmedUser(whereUnconfirmedUser)\nauth.deleteUser(whereUser)\nauth.findCommunity(whereCommunity)\nauth.findCommunityAndPrivilege(whereCommunity, wherePrivilege)\nauth.findPrivilege(wherePrivilege)\nauth.findSession(whereUser)\nauth.findSessionByUser(whereUser)\nauth.findUnconfirmedUser(whereUnconfirmedUser)\nauth.findUser(whereUser)\nauth.findUserAndCommunity(whereUser, whereCommunity)\nauth.findUserAndPrivilege(whereUser, wherePrivilege)\nauth.login(whereUser)\nauth.logout(whereSession)\nauth.logoutByUser(whereUser)\nauth.refresh(whereSession)\nauth.refreshAll()\nauth.registerCommunity(communityDetails)\nauth.registerPrivilege(privilegeDetails)\nauth.revokePrivilegeFromCommunity(wherePrivilege, whereCommunity)\nauth.revokePrivilegeFromUser(wherePrivilege, whereUser)\nauth.registerUnconfirmedUser(userDetails)\nauth.revokeUserFromCommunity(whereUser, whereCommunity)\nauth.unregisterCommunity(whereCommunity)\nauth.unregisterPrivilege(wherePrivilege)\nauth.unregisterUser(whereUser)\nauth.updateCommunity(whereCommunity)\nauth.updatePrivilege(wherePrivilege)\nauth.updateUser(whereUser)\n```\n\n### API `where*` parameters\n\nThe `whereToSQL` is located in the `utils.js` file, here:\n\n - [https://github.com/allnulled/mysql-auth/blob/master/src/utils.js](https://github.com/allnulled/mysql-auth/blob/master/src/utils.js)\n\nThis method is the one that transforms our `where*` parameters into real SQL code.\n\nIt accepts `Object` or `Array`.\n\nWhen it is an `Object`, it uses operator `=` for all the properties.\n\nWhen it is an `Array`, it can use other operator apart from `=` to bind the properties.\n\nThe name of the table, in some contexts, can be omitted (in most of the contexts), as the function can be provided with a default table name. However, it is up to one to override this default value. This can be easily achieved by putting a `.` in the property name to separate the table and the column names.\n\nFor more information about how you can use it, you can check the tests files, here:\n\n - [https://github.com/allnulled/mysql-auth/tree/master/test](https://github.com/allnulled/mysql-auth/tree/master/test)\n\n\n### API signatures\n\nThese are the signatures of the methods of the `mysql-auth` API.\n\n\n\n-----\n\n##### `const AuthSystem = require(\"mysql-auth\")`\n\n\n\n\n-----\n\n##### `const authSystem = AuthSystem.create(...)`\n\n\n\n\n\n-----\n\n##### `auth.assignPrivilegeToCommunity(wherePrivilege:Object, whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.assignPrivilegeToUser(wherePrivilege:Object, whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.assignUserToCommunity(whereUser:Object, whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.can(token:String, privilege:Object|String, defaultPolicy:Boolean):Promise`\n\n\n\n\n-----\n\n##### `auth.authenticate(whereSession:Object, settings:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.canMultiple(token:String, canArgsList:Array\u003cObject|String\u003e):Promise`\n\n\n\n\n-----\n\n##### `auth.cannot(token:String, privilege:Object|String, defaultPolicy:Boolean):Promise`\n\n\n\n\n-----\n\n##### `auth.cannotMultiple(token:String, canArgsList:Array\u003cObject|String\u003e):Promise`\n\n\n\n\n\n\n\n\n\n\n\n\n\n-----\n\n##### `auth.confirmUser(user:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.createTables():Promise`\n\n\n\n\n-----\n\n##### `auth.deleteCommunity(whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.deletePrivilege(wherePrivilege:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.deleteTables():Promise`\n\n\n\n\n-----\n\n##### `auth.deleteUnconfirmedUser(whereUnconfirmedUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.deleteUser(whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findCommunity(whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findCommunityAndPrivilege(whereCommunity:Object, wherePrivilege:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findPrivilege(wherePrivilege:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findSession(whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findSessionByUser(whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findUnconfirmedUser(whereUnconfirmedUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findUser(whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findUserAndCommunity(whereUser:Object, whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.findUserAndPrivilege(whereUser:Object, wherePrivilege:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.login(whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.logout(whereSession:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.logoutByUser(whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.refresh(whereSession:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.refreshAll():Promise`\n\n\n\n\n-----\n\n##### `auth.registerCommunity(communityDetails:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.registerPrivilege(privilegeDetails:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.registerUnconfirmedUser(userDetails:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.revokePrivilegeFromCommunity(wherePrivilege:Object, whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.revokePrivilegeFromUser(wherePrivilege:Object, whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.revokeUserFromCommunity(whereUser:Object, whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.unregisterCommunity(whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.unregisterPrivilege(wherePrivilege:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.updateCommunity(whereCommunity:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.updatePrivilege(wherePrivilege:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.unregisterUser(whereUser:Object):Promise`\n\n\n\n\n-----\n\n##### `auth.updateUser(whereUser:Object):Promise`\n\n\n\n\n\n-------\n\nThe signatures are not yet documented. If anyone asks for them, I can document them. Otherwise, this is enough for me.\n\n\n## License\n\nThis project is under [WTFPL or What The Fuck Public License](https://es.wikipedia.org/wiki/WTFPL), which basically means *'do what you want'*.\n\n## Issues\n\nPlease, share issues and suggestions [here](https://github.com/allnulled/mysql-auth).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallnulled%2Fmysql-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallnulled%2Fmysql-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallnulled%2Fmysql-auth/lists"}