{"id":27233083,"url":"https://github.com/expresso/auth","last_synced_at":"2025-04-10T14:11:24.345Z","repository":{"id":33082958,"uuid":"151322242","full_name":"expresso/auth","owner":"expresso","description":"Expresso authenticator middleware","archived":false,"fork":false,"pushed_at":"2024-03-07T19:00:37.000Z","size":151,"stargazers_count":3,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-01T11:37:33.872Z","etag":null,"topics":["jwt"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/expresso.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,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-10-02T20:55:37.000Z","updated_at":"2023-12-28T19:28:23.000Z","dependencies_parsed_at":"2023-11-12T12:29:22.609Z","dependency_job_id":"921ec3e1-76fa-4167-b6a6-02c03596b5d4","html_url":"https://github.com/expresso/auth","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/expresso%2Fauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/expresso%2Fauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/expresso%2Fauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/expresso%2Fauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/expresso","download_url":"https://codeload.github.com/expresso/auth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248232420,"owners_count":21069487,"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":["jwt"],"created_at":"2025-04-10T14:11:23.740Z","updated_at":"2025-04-10T14:11:24.333Z","avatar_url":"https://github.com/expresso.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Expresso Auth\n\n\u003e Authentication Middleware for Expresso\n\n## Summary\n\n- [Expresso Auth](#expresso-auth)\n  - [Summary](#summary)\n  - [Basic Usage](#basic-usage)\n    - [Options](#options)\n    - [Scopes](#scopes)\n      - [Conditionals](#conditionals)\n  - [URN](#urn)\n    - [Types](#types)\n  - [User-defined properties](#user-defined-properties)\n\n## Basic Usage\n\nInstall:\n\n```sh\n$ npm i @expresso/auth\n```\n\nImport and use:\n\n```js\nimport expresso, { IExpressoConfigOptions } from '@expresso/app'\nimport auth, { IAuthConfig } from '@expresso/auth'\nimport server from '@expresso/server'\n\ninterface IAppConfig extends IAuthConfig, IExpressoConfigOptions {}\n\nconst appFactory = expresso((app, config: IAppConfig, environment) =\u003e {\n  const { jwt, scope, types } = auth.factory(config)\n\n  app.get('/', jwt, types('client'), scopes('namespace:your-scope'), routeHandler)\n})\n\nconst options = {\n  name: 'myApp',\n  jwt: {\n    algorithms: ['HS256'],\n    audience: 'your-audience',\n    issuer: 'your-issuer',\n    secret: 'shhhhh'\n  }\n}\n\nserver.start(appFactory, options)\n```\n\n## URN\n\nSince expresso is an opinionated framework, **you must use an URN** in the format `urn:type:description` for the subject private claim in the JWT\n\n### Types\n\nThe middleware can check if a subject is from a determined type by using the `types('type')` middleware. It'll parse the URN and check if the types are matching, if not, the user will not be authorized.\n\n### Options\n\nThe auth middleware takes an option object as configuration. This object is as follows:\n\n```ts\nexport interface IAuthConfig {\n  jwt: {\n    audience: string\n    issuer: string\n    algorithms?: string[]\n    secret?: string\n  },\n  jwks?: {\n    uri: string\n    cache?: boolean\n    rateLimit?: boolean\n    requestPerMinute?: number\n  }\n}\n```\n\nThe JWT object is required. There's also more than one way to secret your token, this is either with a string secret or a JWKS URI. If the secret is provided, then the JWT string secret will be used. However if you provide the middleware with the `jwks` key and a `uri` property then the middleware will request this URI to find the token.\n\n### Scopes\n\nThis middleware supports scopes. This means you can restrict your token to explicit permission levels using the `scopes` public claim in your JWT token:\n\n```json\n{\n  \"sub\": \"yourSubject\",\n  \"name\": \"John Doe\",\n  \"iat\": 1516239022,\n  \"scope\": \"namespace:your-scope\"\n}\n```\n\nThe `scope` can be either a string or an Array. But it'll only validate if your determined scope is equal to the string or if it is included in the array.\n\n\u003e You can perform wildcard validation using the `*` keyword as long as your scope separator is `.`, for instance, `users.*` will match all the scopes within the `users` namespace, but `users:*` won't.\n\n#### Conditionals\n\nYou can match several scopes using the `or` and `and` keywords.\n\n```ts\napp.get('/', scopes.or(['users.read', 'admin.write']), routeHandler)\n```\n\nWill return `true` if either the `users.read` **or** `admin.write` is present in the `scope` public claim.\n\n```ts\napp.get('/', scopes.and(['users.read', 'admin.write']), routeHandler)\n```\n\nWill return `true` if both the `users.read` **and** `admin.write` is present in the `scope` public claim.\n\n#### User-defined properties\n\nIf you return any other properties that are not in the original JWT spec (like, an email or any other). Auth will put them into `customProperties` in the `req.user` object. Therefore you can access your defined properties as `req.user.customProperties.yourProperty`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexpresso%2Fauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexpresso%2Fauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexpresso%2Fauth/lists"}