{"_id":"@authgear/nestjs","_rev":"2-f26439a01a2c47e9f82ad6fd6b65f690","name":"@authgear/nestjs","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@authgear/nestjs","version":"0.1.0","license":"Apache-2.0","_id":"@authgear/nestjs@0.1.0","maintainers":[{"name":"louischan-oursky","email":"louischan@oursky.com"},{"name":"carmenlau","email":"kmlau.cow@gmail.com"},{"name":"fung-oursky","email":"fung@oursky.com"},{"name":"tung_authgear","email":"tung+authgear@oursky.com"},{"name":"rickmak","email":"rick.mak@gmail.com"}],"dist":{"shasum":"7bc8c555b97185dd0a8547b1cdcc04160a47798e","tarball":"https://registry.npmjs.org/@authgear/nestjs/-/nestjs-0.1.0.tgz","fileCount":19,"integrity":"sha512-DIrFErT2jb1YmHch5h21fgAGdH/ekPRGf8V8xr84tiFD/kK2fa+LH1yBPpoksOEMNQaI4Su/35sy3/GE4abE8Q==","signatures":[{"sig":"MEQCIASiocNZIN+KDrIXAX+WlSRKHnJKNIyv6g0qp+fGTxrfAiAD7VK7UTniDCpVmrFJ9hGEz/E34ujGndJU3MDXSDbAzQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40923},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"0667432e1fab30f9ba416cba8c86989e3f620efd","scripts":{"lint":"eslint \"{src,test}/**/*.ts\"","test":"jest","build":"tsc -p tsconfig.build.json","format":"prettier --write \"{src,test}/**/*.ts\"","test:watch":"jest --watch"},"_npmUser":{"name":"fung-oursky","email":"fung@oursky.com"},"workspaces":["example"],"_npmVersion":"10.9.2","description":"Authgear SDK for NestJS — validate Authgear JWT access tokens and protect routes.","directories":{},"_nodeVersion":"22.15.0","dependencies":{"jose":"^5.9.6"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","rxjs":"^7.8.1","eslint":"^8.57.0","ts-jest":"^29.1.5","prettier":"^3.3.0","supertest":"^7.0.0","typescript":"~5.5.4","@types/jest":"^29.5.12","@types/node":"^20.14.0","@nestjs/core":"^11.0.0","@nestjs/common":"^11.0.0","@nestjs/testing":"^11.0.0","@types/supertest":"^6.0.2","reflect-metadata":"^0.2.2","eslint-config-prettier":"^9.1.0","@nestjs/platform-express":"^11.0.0","@typescript-eslint/parser":"^7.13.0","@typescript-eslint/eslint-plugin":"^7.13.0"},"peerDependencies":{"rxjs":"^7.0.0","@nestjs/core":"^10.0.0 || ^11.0.0","@nestjs/common":"^10.0.0 || ^11.0.0","reflect-metadata":"^0.1.13 || ^0.2.0"},"_npmOperationalInternal":{"tmp":"tmp/nestjs_0.1.0_1781537013563_0.704831477714319","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@authgear/nestjs","version":"0.1.1","description":"Authgear SDK for NestJS — validate Authgear JWT access tokens and protect routes.","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/authgear/authgear-sdk-nestjs.git"},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"workspaces":["example"],"scripts":{"build":"tsc -p tsconfig.build.json","test":"jest","test:watch":"jest --watch","lint":"eslint \"{src,test}/**/*.ts\"","format":"prettier --write \"{src,test}/**/*.ts\""},"dependencies":{"jose":"^5.9.6"},"peerDependencies":{"@nestjs/common":"^10.0.0 || ^11.0.0","@nestjs/core":"^10.0.0 || ^11.0.0","reflect-metadata":"^0.1.13 || ^0.2.0","rxjs":"^7.0.0"},"devDependencies":{"@nestjs/common":"^11.0.0","@nestjs/core":"^11.0.0","@nestjs/platform-express":"^11.0.0","@nestjs/testing":"^11.0.0","@types/jest":"^29.5.12","@types/node":"^20.14.0","@types/supertest":"^6.0.2","@typescript-eslint/eslint-plugin":"^7.13.0","@typescript-eslint/parser":"^7.13.0","eslint":"^8.57.0","eslint-config-prettier":"^9.1.0","jest":"^29.7.0","prettier":"^3.3.0","reflect-metadata":"^0.2.2","rxjs":"^7.8.1","supertest":"^7.0.0","ts-jest":"^29.1.5","typescript":"~5.5.4"},"gitHead":"d47d3c66e018dca517eb563ccde1ce46a868a61b","_id":"@authgear/nestjs@0.1.1","bugs":{"url":"https://github.com/authgear/authgear-sdk-nestjs/issues"},"homepage":"https://github.com/authgear/authgear-sdk-nestjs#readme","_nodeVersion":"22.22.3","_npmVersion":"11.6.2","dist":{"integrity":"sha512-z8I4WKITFuAULvlHc4tTu9DzWAc5wrEDJyWjMF8Oi8SN9c7PTNVQVss8Bkd9LcsRJmL9v19UmlTZmgHaOvFpcw==","shasum":"7721d4630076a252c8fd4256537b05d5ddd31fa7","tarball":"https://registry.npmjs.org/@authgear/nestjs/-/nestjs-0.1.1.tgz","fileCount":19,"unpackedSize":41048,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@authgear%2fnestjs@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIF6fgAlFcfiKR3eUfZEKTAuuo/UpF/gbJk1eP3iwbZcIAiBGv6TviY/lUiOiGQXJkDZepQWZh6r6lryrqonUbGPeHg=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:5c76ec98-6e28-4803-b265-2965d1280f72"}},"directories":{},"maintainers":[{"name":"louischan-oursky","email":"louischan@oursky.com"},{"name":"carmenlau","email":"kmlau.cow@gmail.com"},{"name":"fung-oursky","email":"fung@oursky.com"},{"name":"tung_authgear","email":"tung+authgear@oursky.com"},{"name":"rickmak","email":"rick.mak@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nestjs_0.1.1_1781537683339_0.8011457186446265"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-15T15:23:33.408Z","modified":"2026-06-15T15:34:43.804Z","0.1.0":"2026-06-15T15:23:33.725Z","0.1.1":"2026-06-15T15:34:43.463Z"},"license":"Apache-2.0","description":"Authgear SDK for NestJS — validate Authgear JWT access tokens and protect routes.","maintainers":[{"name":"louischan-oursky","email":"louischan@oursky.com"},{"name":"carmenlau","email":"kmlau.cow@gmail.com"},{"name":"fung-oursky","email":"fung@oursky.com"},{"name":"tung_authgear","email":"tung+authgear@oursky.com"},{"name":"rickmak","email":"rick.mak@gmail.com"}],"readme":"# Authgear SDK for NestJS\n\n[![@authgear/nestjs](https://img.shields.io/npm/v/@authgear/nestjs.svg?label=@authgear/nestjs)](https://www.npmjs.com/package/@authgear/nestjs)\n[![@authgear/nestjs](https://img.shields.io/npm/dt/@authgear/nestjs.svg?label=@authgear/nestjs)](https://www.npmjs.com/package/@authgear/nestjs)\n![License](https://img.shields.io/badge/license-Apache--2.0-blue)\n\nWith Authgear SDK for NestJS, you can protect your NestJS resource server (API) with [Authgear](https://www.authgear.com/) in just **a few lines of code**.\nIt validates Authgear **JWT access tokens** offline using OIDC discovery and JWKS — no network round-trip to Authgear on every request — and provides a NestJS module, an auth guard, and decorators for reading the authenticated user.\n\n**Quick links** — 📚 [Documentation](https://authgear.github.io/authgear-sdk-nestjs/) · 🏁 [Getting Started](#getting-started) · 🛠️ [Troubleshooting](#troubleshooting) · 👥 [Contributing](#contributing)\n\n## What is Authgear?\n\n[Authgear](https://www.authgear.com/) is a highly adaptable identity-as-a-service (IDaaS) platform for web and mobile applications.\nAuthgear makes user authentication easier and faster to implement by integrating it into various types of applications — from single-page web apps to mobile applications to API services.\n\n### Key Features\n\n- Zero-trust authentication architecture with [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) standard.\n- Easy-to-use interfaces for user registration and login, including email, phone, username as login ID, and password, OTP, magic links, etc.\n- Support for a wide range of identity providers, such as [Google](https://developers.google.com/identity), [Apple](https://support.apple.com/en-gb/guide/deployment/depa64848f3a/web), and [Azure Active Directory](https://azure.microsoft.com/en-gb/products/active-directory/).\n- Support for Passkeys, biometric login, and Multi-Factor Authentication (MFA) such as SMS/email-based verification and authenticator apps with TOTP.\n\nThis SDK focuses on the **resource server** side: verifying the JWT access tokens that Authgear issues, so your NestJS API can trust the caller's identity.\n\n## Requirements\n\n- **NestJS** >= 10 (works with NestJS 10 and 11)\n- **Node.js** >= 18\n- **\"Issue JWT as access token\" enabled** for your Authgear application — this SDK validates JWT access tokens offline and does not support opaque tokens.\n\n## Installation\n\n```sh\nnpm install @authgear/nestjs jose\n```\n\n## Getting Started\n\n### 1. Enable JWT access tokens in Authgear\n\nIn the [Authgear Portal](https://portal.authgear.com/), open your application's settings and enable **\"Issue JWT as access token\"**. Without this, Authgear issues opaque access tokens, which this SDK cannot validate offline.\n\n### 2. Register the module\n\nRegister `AuthgearModule.forRoot()` in your root module. Setting `global: true` registers `AuthgearAuthGuard` as a global guard so every route is protected by default.\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport { AuthgearModule } from '@authgear/nestjs';\n\n@Module({\n  imports: [\n    AuthgearModule.forRoot({\n      endpoint: 'https://my-project.authgear.cloud',\n      global: true, // register AuthgearAuthGuard as a global guard\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\nPrefer to load configuration asynchronously (e.g. from `ConfigService`)? Use `forRootAsync()`:\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport { ConfigModule, ConfigService } from '@nestjs/config';\nimport { AuthgearModule } from '@authgear/nestjs';\n\n@Module({\n  imports: [\n    ConfigModule.forRoot(),\n    AuthgearModule.forRootAsync({\n      global: true,\n      imports: [ConfigModule],\n      inject: [ConfigService],\n      useFactory: (config: ConfigService) => ({\n        endpoint: config.getOrThrow<string>('AUTHGEAR_ENDPOINT'),\n        clientID: config.get<string>('AUTHGEAR_CLIENT_ID'),\n      }),\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n### 3. Protect your routes\n\nWhen you register the module with `global: true`, every route requires a valid Bearer token by default. Use the `@Public()` decorator to opt a handler out of authentication:\n\n```ts\n// app.controller.ts\nimport { Controller, Get } from '@nestjs/common';\nimport { Public } from '@authgear/nestjs';\n\n@Controller()\nexport class AppController {\n  @Public()\n  @Get('health')\n  health() {\n    return { ok: true };\n  }\n}\n```\n\nIf you did **not** register the guard globally, protect individual routes (or controllers) with `@UseGuards(AuthgearAuthGuard)`:\n\n```ts\nimport { Controller, Get, UseGuards } from '@nestjs/common';\nimport { AuthgearAuthGuard } from '@authgear/nestjs';\n\n@Controller('me')\n@UseGuards(AuthgearAuthGuard)\nexport class MeController {\n  @Get()\n  me() {\n    /* ... */\n  }\n}\n```\n\n### 4. Read the authenticated user\n\nUse the `@CurrentUser()` parameter decorator to read the verified token claims in a protected handler:\n\n```ts\n// app.controller.ts\nimport { Controller, Get } from '@nestjs/common';\nimport { CurrentUser, AuthgearClaims } from '@authgear/nestjs';\n\n@Controller()\nexport class AppController {\n  @Get('me')\n  me(@CurrentUser() user: AuthgearClaims) {\n    return {\n      userId: user.sub,\n      isVerified: user.isVerified,\n    };\n  }\n}\n```\n\n`AuthgearClaims` exposes the common claims (`sub`, `iss`, `aud`, `clientID`, `isVerified`, `isAnonymous`, `canReauthenticate`) plus the full decoded JWT payload as `raw` for any custom claims.\n\n## Usage\n\nCallers must send the access token as a Bearer token:\n\n```\nAuthorization: Bearer <jwt-access-token>\n```\n\n### Module options\n\n`forRoot()` and the object returned by the `forRootAsync()` factory accept the following options:\n\n| Option | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `endpoint` | `string` | ✓ | — | Authgear project endpoint, e.g. `https://my-project.authgear.cloud`. Used for OIDC discovery and JWKS. |\n| `clientID` | `string` | | — | If set, the verifier also asserts the token's `client_id` claim equals this value. |\n| `global` | `boolean` | | `false` | Register `AuthgearAuthGuard` as a global `APP_GUARD` so all routes are protected. (`forRoot`/`forRootAsync` option.) |\n| `jwksCacheMaxAge` | `number` | | — | JWKS cache max age in milliseconds (passed through to `jose`). |\n| `clockToleranceSeconds` | `number` | | `0` | Leeway in seconds applied to `exp`/`iat` checks. |\n\nYou can also inject `AuthgearTokenService` directly if you need to verify a token outside of the guard.\n\n## Troubleshooting\n\n**Every request returns `401 Unauthorized`.**\n\n- Confirm **\"Issue JWT as access token\"** is enabled for the application in the Authgear Portal. Opaque tokens cannot be validated offline and will be rejected.\n- Make sure the client sends the token in the `Authorization: Bearer <token>` header.\n- If you set `clientID`, confirm the token's `client_id` claim matches it.\n- If tokens are rejected due to clock skew between your server and Authgear, set `clockToleranceSeconds` to a small value.\n\n**The application fails to start, or the first request errors with a discovery/JWKS error.**\n\n- Check that `endpoint` is the correct Authgear project endpoint and is reachable from your server. The SDK fetches the OIDC discovery document and JWKS from this endpoint.\n\n## Contributing\n\nContributions — documentation, features, bug fixes, tests, or code reviews — are very much welcome.\n\n```sh\ngit clone git@github.com:authgear/authgear-sdk-nestjs.git\ncd authgear-sdk-nestjs\nnpm install\nnpm test\nnpm run build\n```\n\nA runnable NestJS app demonstrating the SDK lives in [`example/`](./example). The documentation site source lives in [`docs/`](./docs) and is published to [https://authgear.github.io/authgear-sdk-nestjs/](https://authgear.github.io/authgear-sdk-nestjs/).\n\nTo join the community, raise your hand on the [Authgear Discord server](https://discord.gg/Kdn5vcYwAS) or the GitHub [discussions board](https://github.com/orgs/authgear/discussions).\n\n## License\n\n[Apache-2.0](./LICENSE)\n\n## Supported and maintained by\n\n<div align=\"center\">\n  <a href=\"https://github.com/authgear\"><img src=\"https://uploads-ssl.webflow.com/60658b46b03f0cf83ac1485d/619e6607eb647619cecee2cf_authgear-logo.svg\" /></a>\n</div>\n\n<p align=\"center\">\n  Authgear is a highly adaptable identity-as-a-service (IDaaS) platform for web and mobile applications. To learn more, visit <a href=\"https://www.authgear.com/\">authgear.com</a>.\n</p>\n","readmeFilename":"README.md","homepage":"https://github.com/authgear/authgear-sdk-nestjs#readme","repository":{"type":"git","url":"git+https://github.com/authgear/authgear-sdk-nestjs.git"},"bugs":{"url":"https://github.com/authgear/authgear-sdk-nestjs/issues"}}