{"id":21064167,"url":"https://github.com/moveaxlab/nestjs-security","last_synced_at":"2026-02-02T18:39:50.217Z","repository":{"id":222162001,"uuid":"755081618","full_name":"moveaxlab/nestjs-security","owner":"moveaxlab","description":"A NestJS library to handle JWT authentication for web and mobile apps.","archived":false,"fork":false,"pushed_at":"2024-07-26T08:28:39.000Z","size":590,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-11T13:17:52.883Z","etag":null,"topics":["jwt","nestjs","security"],"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/moveaxlab.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":"2024-02-09T12:06:27.000Z","updated_at":"2024-07-26T08:28:39.000Z","dependencies_parsed_at":"2024-02-12T18:27:30.417Z","dependency_job_id":"ae0ce760-2325-48e0-bf2a-0de4b54167d1","html_url":"https://github.com/moveaxlab/nestjs-security","commit_stats":null,"previous_names":["moveaxlab/nestjs-security"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/moveaxlab/nestjs-security","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fnestjs-security","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fnestjs-security/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fnestjs-security/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fnestjs-security/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moveaxlab","download_url":"https://codeload.github.com/moveaxlab/nestjs-security/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fnestjs-security/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29017683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-02T18:20:26.228Z","status":"ssl_error","status_checked_at":"2026-02-02T18:20:25.361Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","nestjs","security"],"created_at":"2024-11-19T17:48:35.777Z","updated_at":"2026-02-02T18:39:50.201Z","avatar_url":"https://github.com/moveaxlab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NestJS Security\n\n![NPM](https://img.shields.io/npm/l/@moveaxlab/nestjs-security)\n[![npm](https://img.shields.io/npm/v/@moveaxlab/nestjs-security)](https://www.npmjs.com/package/@moveaxlab/nestjs-security)\n\nThis package contains security utilities for NestJS projects,\nfor both REST and GraphQL API gateways.\nIt supports both express and fastify.\n\n## Installation\n\n```bash\nyarn add @moveaxlab/nestjs-security\n```\n\n## Setup with cookies\n\nFor web applications you can rely on cookies.\n\nInclude the `SecurityModule` inside your application:\n\n```typescript\nimport { SecurityModule } from '@moveaxlab/nestjs-security';\n\n@Module({\n    imports: [\n        SecurityModule.forRoot({\n            type: \"cookie\",\n            cookieDomain: \"localhost\",  // the domain of your app\n            cookieExpirationMilliseconds: 15 * 60 * 1000,\n            jwtSecret: \"secret\",\n            // the name of your cookies\n            accessTokenCookieName: \"access_token\",\n            opaqueTokenCookieName: \"opaque_token\",\n            refreshTokenCookieName: \"refresh_token\",\n        })\n    ]\n})\nexport class AppModule;\n```\n\nRemember to enable [cookie support](https://docs.nestjs.com/techniques/cookies) for your application.\n\nWhen using cookies, you can replace the access token with an opaque token\nif your access token may be too big for HTTP headers.\n\nTo enable the opaque token, install `ioredis` as a dependency,\nand configure the `redis` option.\nThe access token will be stored on the configured redis server,\nand will be replaced in the cookies with a randomly generated token.\n\n## Setup with headers\n\nFor mobile and desktop applications you can rely on authentication headers.\n\n```typescript\nimport { SecurityModule } from '@moveaxlab/nestjs-security';\n\n@Module({\n    imports: [\n        SecurityModule.forRoot({\n            type: \"header\",\n            jwtSecret: \"secret\",\n        })\n    ]\n})\nexport class AppModule;\n```\n\n## Custom token conversion logic\n\nAll configurations accept a `tokenConverter` option to implement\ncustom transformations on the parsed access token.\n\n## Authenticating users\n\nYou can authenticate users based on their role (or token type) or based on the permission.\nThe library assumes that all access tokens contain a `tokenType` field or a `permissions` array.\nAuthentication can be applied on the class level or on the method level.\n\n### @Authenticated\n\nThe library will check that the token type is equal with one of the roles declared in the decorator\n\n```typescript\nimport { Authenticated } from \"@moveaxlab/nestjs-security\";\n\n@Authenticated(\"admin\", \"user\")\nclass MyController {\n  async firstMethod() {\n    // accessible to both admins and users\n  }\n\n  @Authenticated(\"admin\")\n  async secondMethod() {\n    // only accessible to admins\n  }\n}\n```\n\nIn order check that the user has a valid accessToken, but without any required permission or roles you can use the `@Authenticated` decorator without any tokenType.\n\n```typescript\nimport { HasPermission } from \"@moveaxlab/nestjs-security\";\nimport { Authenticated } from \"./authenticated.decorator\";\n\n@Authenticated()\nclass MyController {\n  async getMyProfile() {\n    // only accessibile to authenticated user\n  }\n}\n```\n\n### @HasPermission\n\nThe library will search for the required permission in the `permissions` array.\n\n```typescript\nimport { HasPermission } from \"@moveaxlab/nestjs-security\";\n\n@HasPermission(\"myResource.read\")\nclass MyController {\n  async firstMethod() {\n    // accessible to token with permission myResource.read\n  }\n\n  @HasPermission(\"myResource.write\")\n  async secondMethod() {\n    // only accessible to token with the permissions myResourse.write\n  }\n}\n```\n\n## Setting cookies\n\nUse the `CookieService` to set and unset the access token and refresh token.\n\nWhen using express:\n\n```typescript\nimport { CookieService } from \"@movexlab/nestjs-security\";\nimport { Request, Response } from \"express\";\n\nclass Controller {\n  constructor(private readonly cookieService: CookieService) {}\n\n  async login(@Res({ passthrough: true }) res: Response) {\n    await this.cookieService.setCookies(res, accessToken, refreshToken);\n  }\n\n  async logout(@Req() req: Request, @Res({ passthrough: true }) res: Response) {\n    await this.cookieService.clearCookies(req, res);\n  }\n}\n```\n\nWhen using fastify:\n\n```typescript\nimport { CookieService } from \"@movexlab/nestjs-security\";\nimport { FastifyRequest, FastifyReply } from \"fastify\";\n\nclass Controller {\n  constructor(private readonly cookieService: CookieService) {}\n\n  async login(@Res({ passthrough: true }) res: FastifyReply) {\n    await this.cookieService.setCookies(res, accessToken, refreshToken);\n  }\n\n  async logout(\n    @Req() req: FastifyRequest,\n    @Res({ passthrough: true }) res: FastifyReply,\n  ) {\n    await this.cookieService.clearCookies(req, res);\n  }\n}\n```\n\n### Using GraphQL\n\nIf you are using GraphQL, the request and response must be retrieved\nfrom the GraphQL context.\n\nFor express, setup your GraphQL module like this:\n\n```typescript\nimport { GraphQLModule } from '@nestjs/graphql';\nimport { Request, Response } from 'express';\n\n@Module({\n    imports: [\n        GraphQLModule.forRoot({\n            // ...\n            context: ({ req, res }: { req: Request, res: Response }) =\u003e ({ req, res }),\n        })\n    ]\n})\nexport class AppModule;\n```\n\nWith fastify, the setup should look like this:\n\n```typescript\nimport { GraphQLModule } from '@nestjs/graphql';\nimport { FastifyRequest, FastifyReply } from 'fastify';\n\n@Module({\n    imports: [\n        GraphQLModule.forRoot({\n            // ...\n            context: (req: FastifyRequest, res: FastifyReply) =\u003e ({ req, res }),\n        })\n    ]\n})\nexport class AppModule;\n```\n\nInside your resolvers you can access the request and response objects\nusing the `@Context(\"req\")` and `@Context(\"res\")` decorators.\n\n\u003e If you are using fastify, you cannot access the response using `@Context(\"res\")`\n\u003e due to a bug in `@nestjs/core`.\n\u003e Access it instead with `@Context() { res }: { res: FastifyReply }`.\n\n## Getting the tokens inside a controller or resolver\n\nYou can access the access token and refresh token\ninside your controllers and resolvers using decorators.\n\n```typescript\nimport { Authenticated, AccessToken } from \"@moveaxlab/nestjs-security\";\n\n@Authenticated(\"admin\")\nclass MyController {\n  async myMethod(@AccessToken() token: string) {\n    // use the token here\n  }\n}\n```\n\nThe refresh token can be accessed via decorators when using cookies.\nInclude the `RefreshCookieInterceptor` to retrieve it.\n\n```typescript\nimport {\n  Authenticated,\n  RefreshToken,\n  RefreshCookieInterceptor,\n} from \"@moveaxlab/nestjs-security\";\n\n@Authenticated(\"admin\")\n@UseInterceptors(RefreshCookieInterceptor)\nclass MyController {\n  async myMethod(@RefreshToken() token: string) {\n    // use the token here\n  }\n}\n```\n\nYou can access the parsed access token using the `@User` decorator.\n\n```typescript\nimport { Authenticated, HasPermission, User } from \"@moveaxlab/nestjs-security\";\n\ninterface UserType {\n  tokenType: \"admin\" | \"user\";\n  uid: string;\n  permission: string[];\n  // other information contained in the token\n}\n\n@Authenticated(\"admin\")\nclass MyController {\n  async myMethod(@User() token: UserType) {\n    // use the token here\n  }\n}\n\n@HasPermission(\"myPermission\")\nclass MySecondController {\n  async mySecondMethod(@User() token: UserType) {\n    // use the token here\n  }\n}\n```\n\n## Using different secrets based on the issuer\n\nThe `jwtSecret` options can accept an object mapping the `iss` key\ncontained in the token with the secret or key used to sign the token.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoveaxlab%2Fnestjs-security","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoveaxlab%2Fnestjs-security","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoveaxlab%2Fnestjs-security/lists"}