@nestjs-kitchen/authz 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 yikenman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# @nestjs-kitchen/authz
+
+[![NPM Version](https://img.shields.io/npm/v/%40nestjs-kitchen%2Fauthz)
+](https://www.npmjs.com/package/@nestjs-kitchen/authz)
+![NPM License](https://img.shields.io/npm/l/%40nestjs-kitchen%2Fauthz)
+[![codecov](https://codecov.io/gh/yikenman/nestjs-kitchen/graph/badge.svg?token=43EG2T8LKS&flag=@nestjs-kitchen/authz)](https://codecov.io/gh/yikenman/nestjs-kitchen)
+
+Simplest authentication & authorization module in NextJS.
+
+---
+
+
+## Description
+
+**@nestjs-kitchen/authz** is an easy-to-use TypeScript library to apply JWT/Session authentication and authorization to your NestJS application within **4** steps.
+
+## Features
+
+- JWT based authentication
+- Session based authentication
+- Customizable authorization
+- Simplified setups and APIs 
+- Anonymous access support
+- Simultaneous multiple strategy (JWT/Session) uses
+
+## Install
+
+Once completed NestJS project setup, install this package and its dependencies: 
+
+```bash
+$ npm install --save @nestjs/passport passport @nestjs-kitchen/authz
+```
+
+## Usage
+
+1. Create file `authz.provider.ts`:
+
+    ```typescript
+    // authz.provider.ts
+    import { Injectable } from '@nestjs/common';
+    import { AuthzProviderClass } from '@nestjs-kitchen/authz';
+
+    // The type representing the payload used for authentication.
+    interface Payload {
+    // ...
+    }
+    
+    // The type representing the user entity involved in authentication and authorization.
+    export interface User {
+    // ...
+    }
+    
+    @Injectable()
+    export class AuthzProvider extends AuthzProviderClass<Payload, User> {
+      authenticate(payload: Payload) {
+        // Return payload.
+      };
+
+      createPayload(user: User) {
+        // Return user entity.
+      };
+    }
+    ```
+
+2. Create file `authz.module.ts`:
+
+    ```typescript
+    // authz.module.ts
+    import { createJwtAuthzModule } from '@nestjs-kitchen/authz';
+    import { AuthzProvider } from './authz.provider.ts';
+    
+    export const {
+      AuthzGuard,
+      AuthzService,
+      AuthzModule
+    } = createJwtAuthzModule(AuthzProvider);
+    
+    // Fix typescript type hint error
+    export type AuthzService = InstanceType<typeof AuthzService>;
+    ```
+
+3. Use AuthzGuard in your business controller:
+
+    ```typescript
+    // business.controller.ts
+    import { Controller, Get, Query, UseGuards } from '@nestjs/common';
+    import { AuthzGuard, AuthzService } from './authz.module';
+    
+    @UseGuards(AuthzGuard)
+    @Controller('apply-on-both')
+    export class BusinessController {
+      constructor(private readonly authzService: AuthzService) {}
+      
+      // Escape from AuthzGuard
+      @AuthzGuard.NoVerify()
+      @Get('log-in')
+      async logIn() {
+        // get user from db or other api.
+        const user = // ...
+        // call AuthzService.login to create JWT. 
+        const result = await this.authzService.logIn(user);
+        return result;
+      }
+      
+      @Get('get-user')
+      async getUser() {
+        // AuthzService.getUser can get current request user across services. 
+        const user = await this.authzService.getUser();
+        return user;
+      }
+    }
+    ```
+
+4. Import AuthzModule
+
+    ```typescript
+    // business.module.ts
+    import { Module } from '@nestjs/common';
+    import { ExtractJwt } from '@nestjs-kitchen/authz';
+    import { AuthzModule } from './authz.module';
+    import { BusinessController } from './business.controller';
+    
+    @Module({
+      imports: [
+        // Import and configure JWT strategy
+        AuthzModule.register({
+          jwt: {
+            jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+            secret: '1234567890',
+            algorithm: 'HS256'
+          },
+          // Apply strategy to specific controllers. 
+          routes: [BusinessController]
+        })
+      ],
+      controllers: [BusinessController]
+    })
+    export class BusinessModule {}
+    ```
+
+## Errors
+
+The following errors may be thrown during authentication and authorization:
+
+- AuthzError: The base error type.
+- AuthzVerificationError: Thrown when authentication fails.
+- AuthzAnonymousError: Thrown when authentication returns empty.
+
+### Error handling
+
+See [Catch everything](https://docs.nestjs.com/exception-filters#catch-everything) for handling custom error types.
+
+## Examples
+
+Find more scenarios:
+
+- [Authenticate with JWT](./docs/authenticate-with-jwt.md)
+- [Authenticate & authorize with JWT](./docs/authenticate-&-authorize-with-jwt.md)
+- [Authenticate with Session](./docs/authenticate-with-session.md)
+- [Authenticate & authorize with Session](./docs/authenticate-&-authorize-with-session.md)
+- [Use JWT with refresh token](./docs/use-jwt-with-refresh-token.md)
+- [Use JWT and refresh token via session](./docs/use-jwt-and-refresh-token-via-session.md)
+
+## License
+
+MIT License

package/dist/authz.provider.d.ts

@@ -1,7 +1,46 @@
+/**
+ * Abstract base class for implementing custom authorization logic.
+ *
+ * @template Payload - The type representing the payload used for authentication.
+ * @template User - The type representing the user entity involved in authentication and authorization.
+ */
 declare abstract class AuthzProviderClass<Payload, User> {
+    /**
+     * Creates a payload from the given user.
+     *
+     * This method is intended to transform a user entity into a payload, which can be used
+     * for token generation or other authentication mechanisms.
+     *
+     * @param {User} user - The user entity to create the payload for.
+     * @returns {Payload | Promise<Payload>} A payload derived from the user entity,
+     * or a promise resolving to the payload.
+     */
     abstract createPayload(user: User): Payload | Promise<Payload>;
+    /**
+     * Authenticates a given payload to retrieve a user.
+     *
+     * This method is used to validate a payload and map it back to a user entity,
+     * typically as part of a token-based authentication workflow.
+     *
+     * @param {Payload} payload - The payload to authenticate.
+     * @returns {User | Promise<User>} The authenticated user, or a promise resolving to the user.
+     */
     abstract authenticate(payload: Payload): User | Promise<User>;
-    authorize(_uesr: User, _metaData?: unknown): boolean | Promise<boolean>;
+    /**
+     * (**Optional**: Implement this method only if authorization is required.)
+     *
+     * Authorizes a user based on the provided metadata.
+     *
+     * This method checks if the given user is authorized to perform a specific action based on
+     * the provided metadata. If implemented, this method enables the authorization check; otherwise,
+     * only authentication will be performed.
+     *
+     * @param {User} _user - The user entity that needs to be authorized.
+     * @param {unknown} [_metaData] - Optional metadata that can influence the authorization decision.
+     * @returns {boolean | Promise<boolean>} `true` if the user is authorized, `false` otherwise,
+     * or a promise that resolves to the authorization result.
+     */
+    authorize(_user: User, _metaData?: unknown): boolean | Promise<boolean>;
 }
 
 export { AuthzProviderClass };

package/dist/authz.provider.js

@@ -22,7 +22,21 @@ __export(authz_provider_exports, {
 });
 module.exports = __toCommonJS(authz_provider_exports);
 const _AuthzProviderClass = class _AuthzProviderClass {
-  authorize(_uesr, _metaData) {
+  /**
+  * (**Optional**: Implement this method only if authorization is required.)
+  *
+  * Authorizes a user based on the provided metadata.
+  *
+  * This method checks if the given user is authorized to perform a specific action based on
+  * the provided metadata. If implemented, this method enables the authorization check; otherwise,
+  * only authentication will be performed.
+  *
+  * @param {User} _user - The user entity that needs to be authorized.
+  * @param {unknown} [_metaData] - Optional metadata that can influence the authorization decision.
+  * @returns {boolean | Promise<boolean>} `true` if the user is authorized, `false` otherwise,
+  * or a promise that resolves to the authorization result.
+  */
+  authorize(_user, _metaData) {
     return true;
   }
 };

package/dist/errors.d.ts

@@ -1,10 +1,19 @@
+/**
+ * Internal error type.
+ */
 declare class AuthzError extends Error {
     cause?: unknown;
     constructor(message?: string, cause?: unknown);
 }
+/**
+ * Internal error type for verification error.
+ */
 declare class AuthzVerificationError extends AuthzError {
     constructor(message?: string, cause?: unknown);
 }
+/**
+ * Internal error type for anonymous error.
+ */
 declare class AuthzAnonymousError extends AuthzError {
     constructor(message?: string, cause?: unknown);
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { AuthzProviderClass } from './authz.provider.js';
 export { User } from './user.decorator.js';
-export { AuthzError, AuthzVerificationError } from './errors.js';
+export { AuthzAnonymousError, AuthzError, AuthzVerificationError } from './errors.js';
 export { ExtractJwt, JwtFromRequestFunction } from './jwt/extract-jwt.js';
 export { createJwtAuthzModule } from './jwt/jwt-authz.module.js';
 export { cereateSessionAuthzModule } from './session/session-authz.module.js';

package/dist/index.js

@@ -17,6 +17,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var src_exports = {};
 __export(src_exports, {
+  AuthzAnonymousError: () => import_errors.AuthzAnonymousError,
   AuthzError: () => import_errors.AuthzError,
   AuthzProviderClass: () => import_authz.AuthzProviderClass,
   AuthzVerificationError: () => import_errors.AuthzVerificationError,
@@ -33,6 +34,7 @@ var import_jwt = require("./jwt");
 var import_session = require("./session");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AuthzAnonymousError,
   AuthzError,
   AuthzProviderClass,
   AuthzVerificationError,

package/dist/jwt/extract-jwt.d.ts

@@ -7,6 +7,11 @@ declare const parseAuthHeader: (hdrValue: unknown) => {
 interface JwtFromRequestFunction<T = any> {
     (req: T): string | null;
 }
+/**
+ * Utility factory function for creating extractor functions that retrieve JWT from HTTP requests.
+ *
+ * Same as `passportjs` [jwt extractors](https://www.passportjs.org/packages/passport-jwt/#included-extractors)
+ */
 declare const ExtractJwt: {
     /**
      * Creates an extractor function to retrieve a token from the request header.

package/dist/jwt/jwt-authz.guard.js

@@ -103,24 +103,21 @@ const createJwtAuthzGuard = /* @__PURE__ */ __name(([JWT_STRATEGY, AUTHZ_PROVIDE
         context.getClass(),
         context.getHandler()
       ]));
+      if (paramsList.length && Boolean(paramsList[paramsList.length - 1].options?.public)) {
+        store.guardResult = true;
+        return true;
+      }
       const contextParamsList = (0, import_utils.getContextAuthzMetaParamsList)(paramsList, {
         defaultOverride: this.jwtAuthzOptions.defaultOverride,
         skipFalsyMetadata: this.jwtAuthzOptions.skipFalsyMetadata
       });
-      if (!contextParamsList.length) {
-        return true;
-      }
       const req = context.switchToHttp().getRequest();
       store.allowAnonymous = (0, import_utils.getAllowAnonymous)(contextParamsList, {
         defaultAllowAnonymous: this.jwtAuthzOptions.defaultAllowAnonymous
       });
       await super.canActivate(context);
-      if (typeof this.authzProvider.authorize !== "function") {
-        store.guardResult = true;
-        return true;
-      }
       const user = (0, import_utils.getPassportProperty)(req);
-      if (!user && store.allowAnonymous) {
+      if (store.allowAnonymous && !user) {
         return true;
       }
       for (const ele of contextParamsList) {

package/dist/jwt/jwt-authz.interface.d.ts

@@ -9,13 +9,39 @@ import '../authz.provider.js';
 import 'cookie';
 
 type JwtOptions = Omit<VerifyOptions, 'algorithms' | 'audience' | 'issuer'> & SignOptions & {
+    /**
+     * Function that accepts a request as the only parameter and returns either the JWT as a string or null.
+     *
+     * Same as `passport-jwt` [jwtFromRequest option](https://www.passportjs.org/packages/passport-jwt/#configure-strategy).
+     */
     jwtFromRequest: JwtFromRequestFunction | JwtFromRequestFunction[];
+    /**
+     * Secret string used for HMAC algorithms.
+     */
     secret?: Secret;
+    /**
+     * PEM-encoded private key used for RSA and ECDSA algorithms.
+     */
     privateKey?: PrivateKey;
+    /**
+     * PEM-encoded public key corresponding to the `privateKey` used for RSA and ECDSA algorithms.
+     */
     publicKey?: PublicKey;
 };
 type JwtAuthzModuleOptions = Partial<AuthzModuleBaseOptions> & {
+    /**
+     * JWT sign & verify options.
+     *
+     * This combines `jsonwebtoken` [sign options](https://www.npmjs.com/package/jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback)
+     * and [verify options](https://www.npmjs.com/package/jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback).
+     */
     jwt: JwtOptions;
+    /**
+     * Refresh token sign & verify options.
+     *
+     * This combines `jsonwebtoken` [sign options](https://www.npmjs.com/package/jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback)
+     * and [verify options](https://www.npmjs.com/package/jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback).
+     */
     refresh?: JwtOptions;
 };
 declare const normalizedJwtAuthzModuleOptions: (options: JwtAuthzModuleOptions) => {

package/dist/jwt/jwt-authz.module.d.ts

@@ -2,7 +2,7 @@ import './extract-jwt.js';
 import * as _nestjs_core from '@nestjs/core';
 import { JwtAuthzOptions, JwtAuthzModuleOptions, JwtOptions } from './jwt-authz.interface.js';
 import { AuthzProviderClass } from '../authz.provider.js';
-import { AbstractConstructor, RoutesOptions, AuthzDecoParams, MethodParameters, ApplyDecorators, CookieOptionsWithSecret, AuthzModuleRoutesOptions, AuthzModuleBaseOptions } from '../utils/types.js';
+import { AbstractConstructor, RoutesOptions, AuthzDecoParams, MethodParameters, ApplyDecorators, CookieOptionsWithSecret, DeepReadonly, AuthzModuleRoutesOptions, AuthzModuleBaseOptions } from '../utils/types.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import * as _nestjs_common from '@nestjs/common';
 import { MiddlewareConsumer, DynamicModule, Type } from '@nestjs/common';
@@ -24,16 +24,84 @@ declare const OPTIONS_TYPE: Partial<AuthzModuleBaseOptions> & {
 } & Partial<{
     authzProvider?: Type<AuthzProviderClass<unknown, unknown>>;
 } & AuthzModuleRoutesOptions>;
+/**
+ * Creates a JWT module along with its associated guard and service,
+ * with types inferred from the provided implementation of `AuthzProviderClass`.
+ *
+ * @param authzProvider - The implementation class of `AuthzProviderClass`
+ * @returns \{AuthzModule, AuthzGuard, AuthzService}
+ */
 declare const createJwtAuthzModule: <P, U, T extends AuthzProviderClass<P, U>>(authzProvider: AbstractConstructor<T, P, U>) => {
+    /**
+     * A dynamic module used to configure JWT based authentication and authorization features for the application.
+     *
+     * This module can be configured using 2 static methods:
+     *
+     * - `register`
+     * - `registerAsync`
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * ⁣@Module({
+     *   imports: [
+     *     // Import and configure JWT strategy
+     *     AuthzModule.register({
+     *       jwt: {
+     *         jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+     *         secret: '1234567890',
+     *         algorithm: 'HS256'
+     *       },
+     *       // Enable refresh token handling
+     *       refresh: {
+     *         jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+     *         secret: '0987654321',
+     *         algorithm: 'HS256'
+     *       },
+     *       // Apply strategy to specific controllers.
+     *       routes: [BusinessController]
+     *     })
+     *   ],
+     *   controllers: [BusinessController]
+     * })
+     * export class BusinessModule {}
+     * ```
+     */
     AuthzModule: {
         new (routesOpt: RoutesOptions): {
             [x: string]: any;
             readonly routesOpt: RoutesOptions;
             configure(consumer: MiddlewareConsumer): void;
         };
+        /**
+         * Configures authz module.
+         */
         register(options: Omit<typeof OPTIONS_TYPE, "authzProvider">): DynamicModule;
+        /**
+         * Configures authz module asynchronously.
+         */
         registerAsync(options: Omit<typeof ASYNC_OPTIONS_TYPE, "authzProvider">): DynamicModule;
     };
+    /**
+     * A custom guard that applies authentication to controllers.
+     *
+     * This guard also provides 4 utility decorators to apply and modify authorization:
+     *
+     * - `@AuthzGuard.Verify`: Used to verify the user's authorization for specific meta data.
+     * - `@AuthzGuard.NoVerify`: Used to `skip` authentication & authorization checks for specific routes.
+     * - `@AuthzGuard.Apply`: A simplified version of `@UseGuards(AuthzGuard)` and `@AuthzGuard.Verify`, combining both for convenience.
+     * - `@AuthzGuard.Refresh`: Used to ensure that only using refresh token for authentication on specific routes, for refreshing JWT tokens.
+     *
+     * ### Usage:
+     *
+     * ```typescript
+     * ⁣@UseGuards(AuthzGuard)
+     * ⁣@Controller(/⁣/ ...)
+     * export class BusinessController {
+     *   // ...
+     * }
+     * ```
+     */
     AuthzGuard: Type<Omit<{
         readonly reflector: _nestjs_core.Reflector;
         readonly authzProvider: AuthzProviderClass<unknown, unknown>;
@@ -50,14 +118,81 @@ declare const createJwtAuthzModule: <P, U, T extends AuthzProviderClass<P, U>>(a
         } = any>(request: TRequest): Promise<void>;
         getRequest(context: _nestjs_common.ExecutionContext): any;
     }, "als" | "jwtAuthzOptions" | "reflector" | "authzProvider">> & {
+        /**
+         * Verifies the user's authorization for specific meta data.
+         *
+         * ### Usage
+         *
+         * ```typescript
+         * ⁣@UseGuards(AuthzGuard)
+         * ⁣@Controller(/⁣/ ...)
+         * export class BusinessController {
+         *  ⁣@AuthzGuard.Verify(/⁣/ mata datas used to authorize user)
+         *  ⁣@Get()
+         *  async method() {
+         *    // ...
+         *  }
+         * }
+         * ```
+         */
         Verify: (...args: AuthzDecoParams<MethodParameters<T, "authorize">[1]>) => ApplyDecorators;
+        /**
+         * Skips authentication & authorization checks for specific routes.
+         *
+         * ### Usage
+         *
+         * ```typescript
+         * ⁣@UseGuards(AuthzGuard)
+         * ⁣@Controller(/⁣/ ...)
+         * export class BusinessController {
+         *  ⁣@AuthzGuard.NoVerify()
+         *  ⁣@Get()
+         *  async publicMethod() {
+         *    // ...
+         *  }
+         * }
+         * ```
+         */
         NoVerify: () => MethodDecorator & ClassDecorator;
         /**
-         * take highest priority
+         * Ensures that only the refresh token is used for authentication on specific routes, for refreshing JWT tokens.
+         *
+         * ### Usage
+         *
+         * ```typescript
+         * ⁣@UseGuards(AuthzGuard)
+         * ⁣@Controller(/⁣/ ...)
+         * export class BusinessController {
+         *  ⁣@AuthzGuard.Refresh()
+         *  ⁣@Get()
+         *  async refreshToken() {
+         *    // ...
+         *  }
+         * }
+         * ```
          */
         Refresh: () => MethodDecorator & ClassDecorator;
+        /**
+         * A simplified version of `@UseGuards(AuthzGuard)` and `@AuthzGuard.Verify()`, combining both for convenience
+         *
+         * ### Usage
+         *
+         * ```typescript
+         * ⁣@Controller(/⁣/ ...)
+         * export class BusinessController {
+         *   ⁣@AuthzGuard.Apply(/⁣/ mata datas used to authorize user)
+         *   ⁣@Get()
+         *   async refreshToken() {
+         *     // ...
+         *   }
+         * }
+         * ```
+         */
         Apply: (...rest: Parameters<(...args: AuthzDecoParams<MethodParameters<T, "authorize">[1]>) => ApplyDecorators>) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
     };
+    /**
+     * A custom servcie to provide methods to handle authentication and authorization.
+     */
     AuthzService: Type<Omit<{
         readonly authzProvider: AuthzProviderClass<P, U>;
         readonly jwtAuthzOptions: JwtAuthzOptions;
@@ -73,7 +208,7 @@ declare const createJwtAuthzModule: <P, U, T extends AuthzProviderClass<P, U>>(a
             token: string;
         } | undefined>;
         setCookie(name: string, value: string, options?: CookieOptionsWithSecret | undefined): void;
-        getUser(): U | undefined;
+        getUser(): DeepReadonly<U> | undefined;
     }, "als" | "jwtAuthzOptions" | "authzProvider">>;
 };
 

package/dist/jwt/jwt-authz.module.js

@@ -185,6 +185,9 @@ const createJwtAuthzModule = /* @__PURE__ */ __name((authzProvider) => {
       __publicField(this, "routesOpt");
       this.routesOpt = routesOpt;
     }
+    /**
+    * Configures authz module.
+    */
     static register(options) {
       const jwtAuthzOptions = (0, import_jwt_authz2.normalizedJwtAuthzModuleOptions)(options);
       return (0, import_utils.mergeDynamicModuleConfigs)(super.register({
@@ -199,6 +202,9 @@ const createJwtAuthzModule = /* @__PURE__ */ __name((authzProvider) => {
         ]
       });
     }
+    /**
+    * Configures authz module asynchronously.
+    */
     static registerAsync(options) {
       return (0, import_utils.mergeDynamicModuleConfigs)(super.registerAsync({
         ...options,
@@ -233,8 +239,66 @@ const createJwtAuthzModule = /* @__PURE__ */ __name((authzProvider) => {
     ])
   ], JwtAuthzModule);
   return {
+    /**
+    * A dynamic module used to configure JWT based authentication and authorization features for the application.
+    *
+    * This module can be configured using 2 static methods:
+    *
+    * - `register`
+    * - `registerAsync`
+    *
+    * ### Usage
+    *
+    * ```typescript
+    * ⁣@Module({
+    *   imports: [
+    *     // Import and configure JWT strategy
+    *     AuthzModule.register({
+    *       jwt: {
+    *         jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+    *         secret: '1234567890',
+    *         algorithm: 'HS256'
+    *       },
+    *       // Enable refresh token handling
+    *       refresh: {
+    *         jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+    *         secret: '0987654321',
+    *         algorithm: 'HS256'
+    *       },
+    *       // Apply strategy to specific controllers.
+    *       routes: [BusinessController]
+    *     })
+    *   ],
+    *   controllers: [BusinessController]
+    * })
+    * export class BusinessModule {}
+    * ```
+    */
     AuthzModule: JwtAuthzModule,
+    /**
+    * A custom guard that applies authentication to controllers.
+    *
+    * This guard also provides 4 utility decorators to apply and modify authorization:
+    *
+    * - `@AuthzGuard.Verify`: Used to verify the user's authorization for specific meta data.
+    * - `@AuthzGuard.NoVerify`: Used to `skip` authentication & authorization checks for specific routes.
+    * - `@AuthzGuard.Apply`: A simplified version of `@UseGuards(AuthzGuard)` and `@AuthzGuard.Verify`, combining both for convenience.
+    * - `@AuthzGuard.Refresh`: Used to ensure that only using refresh token for authentication on specific routes, for refreshing JWT tokens.
+    *
+    * ### Usage:
+    *
+    * ```typescript
+    * ⁣@UseGuards(AuthzGuard)
+    * ⁣@Controller(/⁣/ ...)
+    * export class BusinessController {
+    *   // ...
+    * }
+    * ```
+    */
     AuthzGuard: JwtAuthzGuard,
+    /**
+    * A custom servcie to provide methods to handle authentication and authorization.
+    */
     AuthzService: JwtAuthzService
   };
 }, "createJwtAuthzModule");

package/dist/jwt/jwt-authz.service.d.ts

@@ -1,6 +1,6 @@
 import * as _nestjs_common from '@nestjs/common';
 import { AuthzProviderClass } from '../authz.provider.js';
-import { CookieOptionsWithSecret } from '../utils/types.js';
+import { CookieOptionsWithSecret, DeepReadonly } from '../utils/types.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { JwtAlsType } from './jwt-authz-als.middleware.js';
 import { JwtAuthzOptions } from './jwt-authz.interface.js';
@@ -16,6 +16,14 @@ declare const createJwtAuthzService: <P = unknown, U = unknown>([AUTHZ_PROVIDER,
     readonly authzProvider: AuthzProviderClass<P, U>;
     readonly jwtAuthzOptions: JwtAuthzOptions;
     readonly als: AsyncLocalStorage<JwtAlsType<U>>;
+    /**
+     * Creates a JWT token with a payload generated by AuthzProviderClass.createPayload(). Optionally, includes a refresh token if configured.
+     *
+     * @param user - User entity
+     * @returns
+     * - `token` : The generated JWT access token.
+     * - `refresh` (optional): The generated refresh token, if enabled.
+     */
     logIn(user: U): Promise<{
         token: string;
         refresh: string;
@@ -23,11 +31,24 @@ declare const createJwtAuthzService: <P = unknown, U = unknown>([AUTHZ_PROVIDER,
         token: string;
         refresh?: undefined;
     }>;
+    /**
+     * Refreshes the JWT token for the provided user. If no user is provided, it attempts to retrieve the
+     * current user and generate a new token.
+     *
+     * @param [user] - User entity
+     * @returns
+     */
     refresh(user?: U): Promise<{
         token: string;
     } | undefined>;
+    /**
+     * Sets a secure HTTP cookie with the given name, value, and optional cookie options.
+     */
     setCookie(name: string, value: string, options?: CookieOptionsWithSecret | undefined): void;
-    getUser(): U | undefined;
+    /**
+     * Retrieves the current user associated with the request, if available.
+     */
+    getUser(): DeepReadonly<U> | undefined;
 }, "als" | "jwtAuthzOptions" | "authzProvider">>;
 
 export { createJwtAuthzService };

package/dist/jwt/jwt-authz.service.js

@@ -77,6 +77,14 @@ const createJwtAuthzService = /* @__PURE__ */ __name(([AUTHZ_PROVIDER, JWT_AUTHZ
         throw new import_errors.AuthzError(`InternalError: Missing Refresh sign options.`);
       }
     }
+    /**
+    * Creates a JWT token with a payload generated by AuthzProviderClass.createPayload(). Optionally, includes a refresh token if configured.
+    *
+    * @param user - User entity
+    * @returns
+    * - `token` : The generated JWT access token.
+    * - `refresh` (optional): The generated refresh token, if enabled.
+    */
     async logIn(user) {
       const payload = await this.authzProvider.createPayload(user);
       const token = import_jsonwebtoken.default.sign(payload, this.jwtAuthzOptions.jwt.secretOrPrivateKey, this.jwtAuthzOptions.jwt.sign);
@@ -93,6 +101,13 @@ const createJwtAuthzService = /* @__PURE__ */ __name(([AUTHZ_PROVIDER, JWT_AUTHZ
         token
       };
     }
+    /**
+    * Refreshes the JWT token for the provided user. If no user is provided, it attempts to retrieve the
+    * current user and generate a new token.
+    *
+    * @param [user] - User entity
+    * @returns
+    */
     async refresh(user) {
       if (!this.jwtAuthzOptions.refresh) {
         console.warn(`'refresh' method can only be called when configured in module options.`);
@@ -115,10 +130,16 @@ const createJwtAuthzService = /* @__PURE__ */ __name(([AUTHZ_PROVIDER, JWT_AUTHZ
         token
       };
     }
+    /**
+    * Sets a secure HTTP cookie with the given name, value, and optional cookie options.
+    */
     setCookie(...rest) {
       const store = (0, import_utils.getAlsStore)(this.als);
       store.setCookie(...rest);
     }
+    /**
+    * Retrieves the current user associated with the request, if available.
+    */
     getUser() {
       const store = (0, import_utils.getAlsStore)(this.als);
       const user = store.user;

package/dist/jwt/jwt-authz.strategy.d.ts

@@ -17,24 +17,12 @@ declare const createJwtStrategy: ([JWT_STRATEGY, AUTHZ_PROVIDER, ALS_PROVIDER]:
     readonly als: AsyncLocalStorage<JwtAlsType<unknown>>;
     validate(req: Request): Promise<{}>;
     authenticate(req: Request, options?: any): any;
-    success(user: any, info?: any): void;
-    fail(challenge: any, status: number): void;
-    fail(status: number): void;
-    redirect(url: string, status?: number): void;
-    pass(): void;
-    error(err: Error): void;
 }, "als" | "authzProvider">>;
 declare const createRefreshStrategy: ([JWT_REFRESH_STRATEGY, AUTHZ_PROVIDER, ALS_PROVIDER]: [string, any, any]) => _nestjs_common.Type<Omit<{
     readonly authzProvider: AuthzProviderClass<unknown, unknown>;
     readonly als: AsyncLocalStorage<JwtAlsType<unknown>>;
     validate(req: Request): Promise<{}>;
     authenticate(req: Request, options?: any): any;
-    success(user: any, info?: any): void;
-    fail(challenge: any, status: number): void;
-    fail(status: number): void;
-    redirect(url: string, status?: number): void;
-    pass(): void;
-    error(err: Error): void;
 }, "als" | "authzProvider">>;
 
 export { createJwtStrategy, createRefreshStrategy };

package/dist/session/session-authz.guard.js

@@ -94,24 +94,21 @@ const createSessionAuthzGuard = /* @__PURE__ */ __name(([SESSION_STRATEGY, AUTHZ
         context.getClass(),
         context.getHandler()
       ]));
+      if (paramsList.length && Boolean(paramsList[paramsList.length - 1].options?.public)) {
+        store.guardResult = true;
+        return true;
+      }
       const contextParamsList = (0, import_utils.getContextAuthzMetaParamsList)(paramsList, {
         defaultOverride: this.sessionAuthzOptions.defaultOverride,
         skipFalsyMetadata: this.sessionAuthzOptions.skipFalsyMetadata
       });
-      if (!contextParamsList.length) {
-        return true;
-      }
       const req = context.switchToHttp().getRequest();
       store.allowAnonymous = (0, import_utils.getAllowAnonymous)(contextParamsList, {
         defaultAllowAnonymous: this.sessionAuthzOptions.defaultAllowAnonymous
       });
       await super.canActivate(context);
-      if (typeof this.authzProvider.authorize !== "function") {
-        store.guardResult = true;
-        return true;
-      }
       const user = (0, import_utils.getPassportProperty)(req);
-      if (!user && store.allowAnonymous) {
+      if (store.allowAnonymous && !user) {
         return true;
       }
       for (const ele of contextParamsList) {

package/dist/session/session-authz.interface.d.ts

@@ -6,7 +6,17 @@ import 'express';
 import '../authz.provider.js';
 
 type SessionAuthzModuleOptions = Partial<AuthzModuleBaseOptions> & {
+    /**
+     * Session options.
+     *
+     * Same as `express-session` [session options](https://www.npmjs.com/package/express-session#options).
+     */
     session: SessionOptions & {
+        /**
+         * Option to keep session information after regenerating.
+         *
+         * Same as `passportjs` [keepSessionInfo](https://github.com/jaredhanson/passport/blob/217018dbc46dcd4118dd6f2c60c8d97010c587f8/CHANGELOG.md#L18).
+         */
         keepSessionInfo?: boolean;
     };
 };

package/dist/session/session-authz.module.d.ts

@@ -1,6 +1,6 @@
 import * as _nestjs_core from '@nestjs/core';
 import { AuthzProviderClass } from '../authz.provider.js';
-import { AbstractConstructor, RoutesOptions, AuthzDecoParams, MethodParameters, ApplyDecorators, CookieOptionsWithSecret, AuthzModuleRoutesOptions, AuthzModuleBaseOptions } from '../utils/types.js';
+import { AbstractConstructor, RoutesOptions, AuthzDecoParams, MethodParameters, ApplyDecorators, CookieOptionsWithSecret, DeepReadonly, AuthzModuleRoutesOptions, AuthzModuleBaseOptions } from '../utils/types.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import * as _nestjs_common from '@nestjs/common';
 import { MiddlewareConsumer, DynamicModule, Type } from '@nestjs/common';
@@ -21,7 +21,42 @@ declare const OPTIONS_TYPE: Partial<AuthzModuleBaseOptions> & {
 } & Partial<{
     authzProvider?: Type<AuthzProviderClass<unknown, unknown>>;
 } & AuthzModuleRoutesOptions>;
+/**
+ * Creates a session module along with its associated guard and service,
+ * with types inferred from the provided implementation of `AuthzProviderClass`.
+ *
+ * @param authzProvider - The implementation class of `AuthzProviderClass`
+ * @returns \{AuthzModule, AuthzGuard, AuthzService}
+ */
 declare const cereateSessionAuthzModule: <P, U, T extends AuthzProviderClass<P, U>>(authzProvider: AbstractConstructor<T, P, U>) => {
+    /**
+     * A dynamic module used to configure session based authentication and authorization features for the application.
+     *
+     * This module can be configured using 2 static methods:
+     *
+     * - `register`
+     * - `registerAsync`
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * ⁣@Module({
+     *   imports: [
+     *     // Import and configure session strategy
+     *     AuthzModule.register({
+     *       session: {
+     *         name: 'custom-session-id-name',
+     *         secret: '1234567890'
+     *       },
+     *       // Define routes that use AuthzGuard
+     *       routes: [BusinessController]
+     *     })
+     *   ],
+     *   controllers: [BusinessController]
+     * })
+     * export class BusinessModule {}
+     * ```
+     */
     AuthzModule: {
         new (routesOpt: RoutesOptions, sessionAuthzOptions: SessionAuthzOptions): {
             [x: string]: any;
@@ -30,14 +65,37 @@ declare const cereateSessionAuthzModule: <P, U, T extends AuthzProviderClass<P,
             configure(consumer: MiddlewareConsumer): void;
         };
         /**
-         * Note: DO NOT register the same route in multiple session authz modules, or import the same session authz module in the same module multiple times, express-session middleware will not work properly.
+         * Configures authz module.
+         *
+         * Note: DO NOT register the same routes in multiple session authz modules, or import the same session authz module in the same module multiple times, express-session middleware will not work properly.
          */
         register(options: Omit<typeof OPTIONS_TYPE, "authzProvider">): DynamicModule;
         /**
-         * Note: DO NOT register the same route in multiple session authz modules, express-session middleware will not work properly.
+         * Configures authz module asynchronously.
+         *
+         * Note: DO NOT register the same routes in multiple session authz modules, express-session middleware will not work properly.
          */
         registerAsync(options: typeof ASYNC_OPTIONS_TYPE): DynamicModule;
     };
+    /**
+     * A custom guard that applies authentication to controllers.
+     *
+     * This guard also provides 3 utility decorators to apply and modify authorization:
+     *
+     * - `@AuthzGuard.Verify`: Used to verify the user's authorization for specific meta data.
+     * - `@AuthzGuard.NoVerify`: Used to `skip` authentication & authorization checks for specific routes.
+     * - `@AuthzGuard.Apply`: A simplified version of `@UseGuards(AuthzGuard)` and `@AuthzGuard.Verify`, combining both for convenience.
+     *
+     * ### Usage:
+     *
+     * ```typescript
+     * ⁣@UseGuards(AuthzGuard)
+     * ⁣@Controller(/⁣/ ...)
+     * export class BusinessController {
+     *   // ...
+     * }
+     * ```
+     */
     AuthzGuard: Type<Omit<{
         readonly reflector: _nestjs_core.Reflector;
         readonly authzProvider: AuthzProviderClass<unknown, unknown>;
@@ -54,17 +112,70 @@ declare const cereateSessionAuthzModule: <P, U, T extends AuthzProviderClass<P,
         } = any>(request: TRequest): Promise<void>;
         getRequest(context: _nestjs_common.ExecutionContext): any;
     }, "als" | "reflector" | "authzProvider" | "sessionAuthzOptions">> & {
+        /**
+         * Verifies the user's authorization for specific meta data.
+         *
+         * ### Usage
+         *
+         * ```typescript
+         * ⁣@UseGuards(AuthzGuard)
+         * ⁣@Controller(/⁣/ ...)
+         * export class BusinessController {
+         *  ⁣@AuthzGuard.Verify(/⁣/ mata datas used to authorize user)
+         *  ⁣@Get()
+         *  async method() {
+         *    // ...
+         *  }
+         * }
+         * ```
+         */
         Verify: (...args: AuthzDecoParams<MethodParameters<T, "authorize">[1]>) => ApplyDecorators;
+        /**
+         * Skips authentication & authorization checks for specific routes.
+         *
+         * ### Usage
+         *
+         * ```typescript
+         * ⁣@UseGuards(AuthzGuard)
+         * ⁣@Controller(/⁣/ ...)
+         * export class BusinessController {
+         *  ⁣@AuthzGuard.NoVerify()
+         *  ⁣@Get()
+         *  async publicMethod() {
+         *    // ...
+         *  }
+         * }
+         * ```
+         */
         NoVerify: () => MethodDecorator & ClassDecorator;
+        /**
+         * A simplified version of `@UseGuards(AuthzGuard)` and `@AuthzGuard.Verify()`, combining both for convenience
+         *
+         * ### Usage
+         *
+         * ```typescript
+         * ⁣@Controller(/⁣/ ...)
+         * export class BusinessController {
+         *   ⁣@AuthzGuard.Apply(/⁣/ mata datas used to authorize user)
+         *   ⁣@Get()
+         *   async refreshToken() {
+         *     // ...
+         *   }
+         * }
+         * ```
+         */
         Apply: (...rest: Parameters<(...args: AuthzDecoParams<MethodParameters<T, "authorize">[1]>) => ApplyDecorators>) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
     };
+    /**
+     * A custom servcie to provide methods to handle authentication and authorization.
+     */
     AuthzService: Type<Omit<{
         readonly authzProvider: AuthzProviderClass<P, U>;
         readonly als: AsyncLocalStorage<SessionAlsType<P, U>>;
         logIn(user: U): Promise<void>;
         logOut(): Promise<void>;
         setCookie(name: string, value: string, options?: CookieOptionsWithSecret | undefined): void;
-        getUser(): U | undefined;
+        getUser(): DeepReadonly<U> | undefined;
     }, "als" | "authzProvider">>;
 };
 

package/dist/session/session-authz.module.js

@@ -180,7 +180,9 @@ const cereateSessionAuthzModule = /* @__PURE__ */ __name((authzProvider) => {
       this.routesOpt = routesOpt, this.sessionAuthzOptions = sessionAuthzOptions;
     }
     /**
-    * Note: DO NOT register the same route in multiple session authz modules, or import the same session authz module in the same module multiple times, express-session middleware will not work properly.
+    * Configures authz module.
+    *
+    * Note: DO NOT register the same routes in multiple session authz modules, or import the same session authz module in the same module multiple times, express-session middleware will not work properly.
     */
     static register(options) {
       const sessionAuthzOptions = (0, import_session_authz2.normalizedSessionAuthzModuleOptions)(options);
@@ -197,7 +199,9 @@ const cereateSessionAuthzModule = /* @__PURE__ */ __name((authzProvider) => {
       });
     }
     /**
-    * Note: DO NOT register the same route in multiple session authz modules, express-session middleware will not work properly.
+    * Configures authz module asynchronously.
+    *
+    * Note: DO NOT register the same routes in multiple session authz modules, express-session middleware will not work properly.
     */
     static registerAsync(options) {
       return (0, import_utils.mergeDynamicModuleConfigs)(super.registerAsync({
@@ -234,8 +238,58 @@ const cereateSessionAuthzModule = /* @__PURE__ */ __name((authzProvider) => {
     ])
   ], SessionAuthzModule);
   return {
+    /**
+    * A dynamic module used to configure session based authentication and authorization features for the application.
+    *
+    * This module can be configured using 2 static methods:
+    *
+    * - `register`
+    * - `registerAsync`
+    *
+    * ### Usage
+    *
+    * ```typescript
+    * ⁣@Module({
+    *   imports: [
+    *     // Import and configure session strategy
+    *     AuthzModule.register({
+    *       session: {
+    *         name: 'custom-session-id-name',
+    *         secret: '1234567890'
+    *       },
+    *       // Define routes that use AuthzGuard
+    *       routes: [BusinessController]
+    *     })
+    *   ],
+    *   controllers: [BusinessController]
+    * })
+    * export class BusinessModule {}
+    * ```
+    */
     AuthzModule: SessionAuthzModule,
+    /**
+    * A custom guard that applies authentication to controllers.
+    *
+    * This guard also provides 3 utility decorators to apply and modify authorization:
+    *
+    * - `@AuthzGuard.Verify`: Used to verify the user's authorization for specific meta data.
+    * - `@AuthzGuard.NoVerify`: Used to `skip` authentication & authorization checks for specific routes.
+    * - `@AuthzGuard.Apply`: A simplified version of `@UseGuards(AuthzGuard)` and `@AuthzGuard.Verify`, combining both for convenience.
+    *
+    * ### Usage:
+    *
+    * ```typescript
+    * ⁣@UseGuards(AuthzGuard)
+    * ⁣@Controller(/⁣/ ...)
+    * export class BusinessController {
+    *   // ...
+    * }
+    * ```
+    */
     AuthzGuard: SessionAuthzGuard,
+    /**
+    * A custom servcie to provide methods to handle authentication and authorization.
+    */
     AuthzService: SessionAuthzService
   };
 }, "cereateSessionAuthzModule");

package/dist/session/session-authz.service.d.ts

@@ -1,6 +1,6 @@
 import * as _nestjs_common from '@nestjs/common';
 import { AuthzProviderClass } from '../authz.provider.js';
-import { CookieOptionsWithSecret } from '../utils/types.js';
+import { CookieOptionsWithSecret, DeepReadonly } from '../utils/types.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { SessionAlsType } from './session-authz-als.middleware.js';
 import '@nestjs/common/interfaces';
@@ -11,10 +11,24 @@ import 'express-session';
 declare const createSessionAuthzService: <P = unknown, U = unknown>([AUTHZ_PROVIDER, ALS_PROVIDER]: [any, any]) => _nestjs_common.Type<Omit<{
     readonly authzProvider: AuthzProviderClass<P, U>;
     readonly als: AsyncLocalStorage<SessionAlsType<P, U>>;
+    /**
+     * Creates a session id with a payload generated by AuthzProviderClass.createPayload().
+     *
+     * @param user - User entity
+     */
     logIn(user: U): Promise<void>;
+    /**
+     * Clears current user session.
+     */
     logOut(): Promise<void>;
+    /**
+     * Sets a secure HTTP cookie with the given name, value, and optional cookie options.
+     */
     setCookie(name: string, value: string, options?: CookieOptionsWithSecret | undefined): void;
-    getUser(): U | undefined;
+    /**
+     * Retrieves the current user associated with the request, if available.
+     */
+    getUser(): DeepReadonly<U> | undefined;
 }, "als" | "authzProvider">>;
 
 export { createSessionAuthzService };

package/dist/session/session-authz.service.js

@@ -57,19 +57,33 @@ const createSessionAuthzService = /* @__PURE__ */ __name(([AUTHZ_PROVIDER, ALS_P
         throw new import_errors.AuthzError(`InternalError: Method 'createPayload' from abstract class 'AuthzProvider' must be implemented.`);
       }
     }
+    /**
+    * Creates a session id with a payload generated by AuthzProviderClass.createPayload().
+    *
+    * @param user - User entity
+    */
     async logIn(user) {
       const store = (0, import_utils.getAlsStore)(this.als);
       const payload = await this.authzProvider.createPayload(user);
       return store.logIn(payload);
     }
+    /**
+    * Clears current user session.
+    */
     async logOut() {
       const store = (0, import_utils.getAlsStore)(this.als);
       return store.logOut();
     }
+    /**
+    * Sets a secure HTTP cookie with the given name, value, and optional cookie options.
+    */
     setCookie(...rest) {
       const store = (0, import_utils.getAlsStore)(this.als);
       store.setCookie(...rest);
     }
+    /**
+    * Retrieves the current user associated with the request, if available.
+    */
     getUser() {
       const store = (0, import_utils.getAlsStore)(this.als);
       const user = store.user;

package/dist/session/session-authz.strategy.d.ts

@@ -13,12 +13,6 @@ declare const createSessionAuthzStrategy: ([SESSION_STRATEGY, AUTHZ_PROVIDER, AL
     readonly als: AsyncLocalStorage<SessionAlsType<unknown, unknown>>;
     validate(req: Request): Promise<{}>;
     authenticate(req: Request, options?: any): any;
-    success(user: any, info?: any): void;
-    fail(challenge: any, status: number): void;
-    fail(status: number): void;
-    redirect(url: string, status?: number): void;
-    pass(): void;
-    error(err: Error): void;
 }, "als" | "authzProvider">>;
 
 export { createSessionAuthzStrategy };

package/dist/user.decorator.d.ts

@@ -1,6 +1,22 @@
 import { ExecutionContext } from '@nestjs/common';
 
 declare const userDecoratorFactory: (_data: unknown, ctx: ExecutionContext) => unknown;
+/**
+ * Retrieves the current user associated with the request, if available.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * ⁣@UseGuards(AuthzGuard)
+ * ⁣@Controller(/⁣/ ...)
+ * export class BusinessController {
+ *  ⁣@Get()
+ *  async method(@User() user: User) {
+ *    // ...
+ *  }
+ * }
+ * ```
+ */
 declare const User: (...dataOrPipes: unknown[]) => ParameterDecorator;
 
 export { User, userDecoratorFactory };

package/dist/utils/index.d.ts

@@ -8,7 +8,7 @@ export { getContextAuthzMetaParamsList } from './get-context-authz-meta-params-l
 export { getPassportProperty } from './get-passport-property.js';
 export { mergeDynamicModuleConfigs } from './merge-dynamic-module-configs.js';
 export { decodeMsgpackrString, encodeMsgpackrString } from './msgpackrs.js';
-export { AbstractConstructor, ApplyDecorators, AuthzDecoBaseOptions, AuthzDecoOptions, AuthzDecoParams, AuthzMetaParams, AuthzModuleBaseOptions, AuthzModuleRoutesOptions, CookieOptionsWithSecret, IncludesUndefined, IsEqual, IsNull, IsUnknown, MethodParameters, OmitClassInstance, RoutesOptions, SetRequired, SingleOrArray } from './types.js';
+export { AbstractConstructor, ApplyDecorators, AuthzDecoBaseOptions, AuthzDecoOptions, AuthzDecoParams, AuthzMetaParams, AuthzModuleBaseOptions, AuthzModuleRoutesOptions, CookieOptionsWithSecret, DeepReadonly, IncludesUndefined, IsEqual, IsNull, IsUnknown, MethodParameters, OmitClassInstance, RoutesOptions, SetRequired, SingleOrArray } from './types.js';
 import 'express';
 import '../authz.provider.js';
 import 'node:async_hooks';

package/dist/utils/types.d.ts

@@ -10,6 +10,9 @@ type SetRequired<T, K extends keyof T> = T & {
 type IsEqual<A, B> = (<G>() => G extends A ? 1 : 2) extends <G>() => G extends B ? 1 : 2 ? true : false;
 type IsNull<T> = [T] extends [null] ? true : false;
 type IsUnknown<T> = unknown extends T ? IsNull<T> extends false ? true : false : false;
+type DeepReadonly<T> = {
+    readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
+};
 type CookieOptionsWithSecret = CookieOptions & {
     /**
      * a string or array used to sign cookies.
@@ -17,7 +20,13 @@ type CookieOptionsWithSecret = CookieOptions & {
     secret?: string | string[];
 };
 interface AuthzDecoBaseOptions {
+    /**
+     * When set, overrides the previous metadatas during the authorization, instead of inheriting.
+     */
     override?: boolean;
+    /**
+     * When set, authorization & authentication will be bypassed if authentication returns empty.
+     */
     allowAnonymous?: boolean;
 }
 interface AuthzDecoOptions extends AuthzDecoBaseOptions {
@@ -33,17 +42,49 @@ type IncludesUndefined<T> = undefined extends T ? true : false;
 type AbstractConstructor<T, T1, T2> = new (...args: any[]) => T & AuthzProviderClass<T1, T2>;
 type MethodParameters<T, Method extends keyof T> = T[Method] extends (...args: infer P) => any ? P : never;
 interface AuthzModuleBaseOptions {
+    /**
+     * Property name for registering authenticated user on the HTTP request object.
+     *
+     * @default 'user'
+     */
     passportProperty: string;
+    /**
+     * When set, the current metadata will override previous metadatas during the authorization by default, instead of inheriting.
+     *
+     * @default false
+     */
     defaultOverride: boolean;
+    /**
+     * When set, empty metadata will be `ignored` by default during the authorization.
+     *
+     * @default false
+     */
     skipFalsyMetadata: boolean;
+    /**
+     * When set, authorization & authentication will be bypassed by default if authentication returns empty.
+     *
+     * @default false
+     */
     defaultAllowAnonymous: boolean;
 }
 type AuthzModuleRoutesOptions = {
+    /**
+     * When enabled, becomes a global module and will apply strategy to all routes in the application.
+     *
+     * Note: This option conflicts with the `routes` option.
+     *
+     * @default false
+     */
     global?: boolean;
     /**
-     * Note: DO NOT register the same controller in different modules, their middlewares will not work properly. This is an Nest.js design. Pleases use string instead if requires.
+     * Applies strategy to the specified controllers/routes.
+     *
+     * Note: This option conflicts with the `global` option.
      */
     routes?: SingleOrArray<string | Type | RouteInfo>;
+    /**
+     * Whitelists the specified controllers/routes listed in `routes` options.
+     */
     excludes?: SingleOrArray<string | RouteInfo>;
 };
 type RoutesOptions = {
@@ -53,4 +94,4 @@ type RoutesOptions = {
 };
 type ApplyDecorators = ReturnType<typeof applyDecorators>;
 
-export type { AbstractConstructor, ApplyDecorators, AuthzDecoBaseOptions, AuthzDecoOptions, AuthzDecoParams, AuthzMetaParams, AuthzModuleBaseOptions, AuthzModuleRoutesOptions, CookieOptionsWithSecret, IncludesUndefined, IsEqual, IsNull, IsUnknown, MethodParameters, OmitClassInstance, RoutesOptions, SetRequired, SingleOrArray };
+export type { AbstractConstructor, ApplyDecorators, AuthzDecoBaseOptions, AuthzDecoOptions, AuthzDecoParams, AuthzMetaParams, AuthzModuleBaseOptions, AuthzModuleRoutesOptions, CookieOptionsWithSecret, DeepReadonly, IncludesUndefined, IsEqual, IsNull, IsUnknown, MethodParameters, OmitClassInstance, RoutesOptions, SetRequired, SingleOrArray };

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@nestjs-kitchen/authz",
   "private": false,
-  "description": "Nest TypeScript starter repository",
-  "version": "1.0.0",
+  "description": "Simplest authentication & authorization module in NextJS",
+  "version": "1.1.0",
+  "homepage": "https://github.com/yikenman/nestjs-kitchen",
+  "repository": "https://github.com/yikenman/nestjs-kitchen",
+  "author": "yikenman",
   "license": "MIT",
   "exports": {
     ".": {
@@ -47,6 +50,9 @@
     "tsup": "^8.3.5",
     "typescript": "^5.7.2"
   },
+  "engines": {
+    "node": ">=20.13.0"
+  },
   "peerDependencies": {
     "@nestjs/common": "^10.4.12",
     "@nestjs/core": "^10.4.12",