{"id":18812407,"url":"https://github.com/warrant-dev/warrant-express-middleware","last_synced_at":"2025-04-13T21:13:58.109Z","repository":{"id":43155697,"uuid":"414401933","full_name":"warrant-dev/warrant-express-middleware","owner":"warrant-dev","description":"Expressjs Middleware for enforcing access control on API endpoints using the Warrant API","archived":false,"fork":false,"pushed_at":"2024-06-03T19:04:24.000Z","size":128,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T21:13:51.895Z","etag":null,"topics":["abac","access-control","acl","attribute-based-access-control","authorization","authz","express-middleware","expressjs","javascript","middleware","nodejs","permissions","rbac","role-based-access-control"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/warrant-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-06T23:29:28.000Z","updated_at":"2024-06-03T19:04:28.000Z","dependencies_parsed_at":"2024-11-07T23:33:45.311Z","dependency_job_id":"17dbfc48-bbeb-4293-92de-a20f813dac55","html_url":"https://github.com/warrant-dev/warrant-express-middleware","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warrant-dev%2Fwarrant-express-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warrant-dev%2Fwarrant-express-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warrant-dev%2Fwarrant-express-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warrant-dev%2Fwarrant-express-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/warrant-dev","download_url":"https://codeload.github.com/warrant-dev/warrant-express-middleware/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248782260,"owners_count":21160717,"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":["abac","access-control","acl","attribute-based-access-control","authorization","authz","express-middleware","expressjs","javascript","middleware","nodejs","permissions","rbac","role-based-access-control"],"created_at":"2024-11-07T23:32:42.687Z","updated_at":"2025-04-13T21:13:58.087Z","avatar_url":"https://github.com/warrant-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Warrant Express.js Authorization Middleware\n\nUse [Warrant](https://warrant.dev/) in server-side Express.js projects.\n\n[![npm](https://img.shields.io/npm/v/@warrantdev/warrant-express-middleware)](https://www.npmjs.com/package/@warrantdev/warrant-express-middleware)\n\n## Installation\n\nUse `npm` to install the Warrant module:\n\n```sh\nnpm install @warrantdev/warrant-node\nnpm install @warrantdev/warrant-express-middleware\n```\n\n## Usage\n\n### Initializing the Middleware\n\nImport the `createMiddleware` function and call it with some initialization options to get a configured middleware function you can protect your API routes with:\n\n```js\nconst Warrant = require(\"@warrantdev/warrant-node\");\nconst WarrantMw = require(\"@warrantdev/warrant-express-middleware\");\nconst { hasPermission, hasAccess } = WarrantMw.createMiddleware({\n  client: new Warrant({\n    apiKey: \"api_test_f5dsKVeYnVSLHGje44zAygqgqXiLJBICbFzCiAg1E=\",\n  }),\n  getUserId: (req, res) =\u003e MyUserSession.getUserId(req, res).toString(), // Tell the middleware how to get the current user in your API\n});\n\n// The hasAccess middleware will run before the route code.\napp.get(\n  \"/api/posts/:postId\",\n  hasAccess(\"post\", (req) =\u003e req.params[\"postId\"], \"viewer\"),\n  (req, res) =\u003e {\n    const { postId } = req.params;\n    const post = getPost(postId);\n\n    if (!post) {\n      res.sendStatus(404);\n      return;\n    }\n\n    res.json(post);\n  }\n);\n```\n\nOr using ES modules:\n\n```js\nimport Warrant from \"@warrantdev/warrant-node\";\nimport { createMiddleware } from \"@warrantdev/warrant-express-middleware\";\nconst { hasPermission, hasAccess } = Warrant.createMiddleware({\n  client: new Warrant({\n    apiKey: \"api_test_f5dsKVeYnVSLHGje44zAygqgqXiLJBICbFzCiAg1E=\",\n  }),\n  getUserId: (req, res) =\u003e MyUserSession.getUserId(req, res).toString(), // Tell the middleware how to get the current user in your API\n});\n\n// The hasAccess middleware will run before the route code.\napp.get(\n  \"/api/posts/:postId\",\n  hasAccess(\"post\", (req) =\u003e req.params[\"postId\"], \"viewer\"),\n  (req, res) =\u003e {\n    const { postId } = req.params;\n    const post = getPost(postId);\n\n    if (!post) {\n      res.sendStatus(404);\n      return;\n    }\n\n    res.json(post);\n  }\n);\n```\n\n### Using the Middleware\n\nOnce you've initialized the middleware as shown above, you can use either the `hasPermission` or the `hasAccess` method to protect your Express.js API routes:\n\n#### `hasPermission`\n\n```js\n// The hasPermission middleware will check that the current user\n// has the specified permission before executing the route.\napp.post(\"/api/posts\", hasPermission(\"create-posts\"), (req, res) =\u003e {\n  try {\n    const newPost = createPost(req.body);\n    res.json(newPost);\n  } catch (e) {\n    res.sendStatus(e.code);\n  }\n});\n```\n\n#### `hasAccess`\n\n```js\n// The hasAccess middleware will check that the current user is a \"viewer\"\n// of the particular Post with id postId before executing the route.\napp.get(\n  \"/api/posts/:postId\",\n  hasAccess(\"post\", (req) =\u003e req.params[\"postId\"], \"viewer\"),\n  (req, res) =\u003e {\n    const { postId } = req.params;\n    const post = getPost(postId);\n\n    if (!post) {\n      res.sendStatus(404);\n      return;\n    }\n\n    res.json(post);\n  }\n);\n```\n\nThe `hasPermission` middleware function takes a single argument:\n\n#### `permissionId`\n\n`string` - This is the string id of the permission you want to check for (ex: `\"view-posts\"`).\n\nThe `hasAccess` middleware function takes 3 arguments:\n\n#### `objectType`\n\n`string` - This is the object type you want to perform an access check for. To learn more about creating object types, visit our [documentation](https://docs.warrant.dev/).\n\n#### `getObjectId(req, res)`\n\n`function` - A function executed by the middleware in order to get the id of the object for which to perform the access check. In most scenarios, this will be the value of one of the request params. An example of what this function might look like:\n\n```js\n(req: Request) =\u003e req.params[\"myParam\"];\n```\n\n#### `relation`\n\n`string` - This is the relation you want to perform an access check for. To learn more about relations, visit our [documentation](https://docs.warrant.dev/).\n\n## Configuration Options\n\nThe middleware supports options that allow you to configure how it works during the initialization step. All options are required unless stated that they are optional.\n\n### `clientKey`\n\n`string` - This is the API Key from the Warrant Dashboard. Without this value, the middleware cannot make requests to the Warrant API to perform access checks in your application.\n\n### `getUserId(req, res)`\n\n`function` - A function executed by the middleware in order to get the userId for which to perform an access check. Use this function to tell the middleware how to get the current user's id. Usually this user is determined using the current session or authentication token provided in the request.\n\n### `onAuthorizeFailure(req, res)` (Optional)\n\n`function` - A function executed by the middleware when an access check fails (the user is unauthorized). Use this function to tell the middleware what to do when a user fails an access check. This option defaults to:\n\n```js\n(req: Request, res: Response) =\u003e res.sendStatus(401);\n```\n\nWe’ve used a random API key in these code examples. Replace it with your\n[actual publishable API keys](https://app.warrant.dev) to\ntest this code through your own Warrant account.\n\nFor more information on how to use the Warrant API, please refer to the\n[Warrant API reference](https://docs.warrant.dev).\n\nNote that we may release new [minor and patch](https://semver.org/) versions of\n`@warrantdev/warrant-express-middleware` with small but backwards-incompatible fixes to the type\ndeclarations. These changes will not affect Warrant itself.\n\n## TypeScript support\n\nThis package includes TypeScript declarations for Warrant.\n\n## Warrant Documentation\n\n- [Warrant Docs](https://docs.warrant.dev/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarrant-dev%2Fwarrant-express-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwarrant-dev%2Fwarrant-express-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarrant-dev%2Fwarrant-express-middleware/lists"}