{"id":13780105,"url":"https://github.com/koajs/userauth","last_synced_at":"2025-10-26T14:32:46.735Z","repository":{"id":16013135,"uuid":"18756617","full_name":"koajs/userauth","owner":"koajs","description":"koa user auth middleware","archived":false,"fork":false,"pushed_at":"2023-05-29T09:31:34.000Z","size":80,"stargazers_count":140,"open_issues_count":9,"forks_count":18,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-09T16:19:59.247Z","etag":null,"topics":["koa","koa-middleware"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koajs.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2014-04-14T10:18:19.000Z","updated_at":"2025-02-10T12:50:07.000Z","dependencies_parsed_at":"2023-09-29T22:39:38.533Z","dependency_job_id":null,"html_url":"https://github.com/koajs/userauth","commit_stats":{"total_commits":55,"total_committers":11,"mean_commits":5.0,"dds":0.5454545454545454,"last_synced_commit":"f798f68736dae56437c3e19499a4700c6f23bc62"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fuserauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fuserauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fuserauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fuserauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koajs","download_url":"https://codeload.github.com/koajs/userauth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065281,"owners_count":21041872,"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":["koa","koa-middleware"],"created_at":"2024-08-03T18:01:12.380Z","updated_at":"2025-10-26T14:32:41.708Z","avatar_url":"https://github.com/koajs.png","language":"JavaScript","readme":"# koa-userauth\n\n[![NPM version][npm-image]][npm-url]\n\n[npm-image]: https://img.shields.io/npm/v/koa-userauth.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/koa-userauth\n\n`koa` user auth abstraction layer middleware.\n\n## Install\n\n```bash\nnpm install koa-userauth\n```\n\n## Usage\n\n`koa-userauth` is dependent on [koa-session](https://github.com/koajs/session) or [koa-generic-session](https://github.com/koajs/generic-session).\n\n```js\nvar koa = require('koa');\nvar userauth = require('koa-userauth');\nvar session = require('koa-generic-session');\n\nvar app = new koa();\napp.keys = ['i m secret'];\n\napp.use(session());\napp.use(userauth({\n  match: '/user',\n  // auth system login url\n  loginURLFormatter: function (url) {\n    return 'http://login.demo.com/login?redirect=' + url;\n  },\n  // login callback and getUser info handler\n  getUser: async ctx =\u003e {\n    var token = this.query.token;\n    // get user\n    return user;\n  }\n}));\n```\n\n### Arguments\n\nIf `options.match` or `options.ignore` is `String` instance,\nwe will use [path-match](https://github.com/expressjs/path-match) transfer it to `Regex` instance.\n\n```js\n/**\n * User auth middleware.\n *\n * @param {Object} [options]\n *  - {String|Regex|Function(pathname, ctx)} match, detect which url need to check user auth.\n *      `''` empty string meaning match all, @see `path-match` package.\n *  - {String|Regex|Function(pathname, ctx)} ignore, detect which url no need to check user auth.\n *      If `match` exists, this argument will be ignored.\n *  - {Function(url, rootPath, ctx)} loginURLFormatter, format the login url.\n *  - {String} [rootPath], custom app url root path, default is '/'.\n *  - {String} [loginPath], default is '/login'.\n *  - {String} [loginCallbackPath], default is `options.loginPath + '/callback'`.\n *  - {String} [logoutPath], default is '/logout'.\n *  - {String} [userField], logined user field name on `this.session`, default is 'user', `this.session.user`.\n *  - {Async Function (ctx)} getUser, get user function, must get user info with `req`.\n *  - {Async Function (ctx, user)} [loginCallback], you can handle user login logic here,return [user, redirectUrl]\n *  - {Function(ctx)} [loginCheck], return true meaning logined. default is `true`.\n *  - {Async Function (ctx, user)} [logoutCallback], you can handle user logout logic here.return redirectUrl\n *  - {Function(ctx)} [getRedirectTarget], customize how to get the redirect target after login\n * @return {Async Function (next)} userauth middleware\n * @public\n */\n```\n\n## Login flow\n\n1. unauth user, redirect to `$loginPath?redirect=$currentURL`\n2. user visit `$loginPath`, redirect to `options.loginURLFormatter()` return login url.\n3. user visit $loginCallbackPath, handler login callback logic.\n4. If user login callback check success, will set `req.session[userField]`,\n   and redirect to `$currentURL`.\n5. If login check callback error, next(err).\n6. user visit `$logoutPath`, set `req.session[userField] = null`, and redirect back.\n\n![userauth flow](https://www.lucidchart.com/publicSegments/view/54ede23d-a75c-4690-9408-33a30a008a99/image.png)\n\n\u003e [Source image file](https://www.lucidchart.com/documents/edit/4749f226-b75f-42ef-934f-b89f7bd68c7f?driveId=0ACmMEQjF7GJGUk9PVA)\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":["Middleware"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoajs%2Fuserauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoajs%2Fuserauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoajs%2Fuserauth/lists"}