@navios/jwt 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.7.0] - 2025-12-18
+
+### Added
+
+- **Comprehensive JSDoc Documentation**: Added detailed JSDoc comments to all public APIs including:
+  - `JwtService` class and all methods (`sign`, `signAsync`, `verify`, `verifyAsync`, `decode`)
+  - `provideJwtService` function with overloads
+  - Type definitions and interfaces (`JwtServiceOptions`, `JwtSignOptions`, `JwtVerifyOptions`, etc.)
+  - Error classes (`TokenExpiredError`, `NotBeforeError`, `JsonWebTokenError`)
+- **Enhanced README**: Improved documentation with better examples, clearer API reference, and usage patterns
+
+### Documentation
+
+- Complete JSDoc comments for better IDE support and developer experience
+- Updated README with comprehensive examples and API documentation
+- Clarified usage patterns for synchronous and asynchronous operations
+- Added examples for different JWT algorithms and key management strategies

package/README.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-Navios JWT is a TypeScript library that provides a robust implementation for JSON Web Token (JWT) for a Navios framework operations in your applications. It wraps the functionality of the `jsonwebtoken` library with a service-oriented approach that integrates with the Navios dependency injection system.
+Navios JWT is a TypeScript library that provides a robust implementation for JSON Web Token (JWT) operations in Navios applications. It wraps the functionality of the `jsonwebtoken` library with a service-oriented approach that integrates seamlessly with the Navios dependency injection system.
 
-It was forked from a [NestJS](https://github.com/nestjs/jwt) library and is designed to be used with the Navios framework, providing a seamless experience for signing and verifying JWTs.
+It was forked from a [NestJS](https://github.com/nestjs/jwt) library and is designed to be used with the Navios framework, providing a type-safe and developer-friendly experience for signing and verifying JWTs.
 
 ## Installation
 
@@ -16,84 +16,222 @@ yarn add @navios/jwt
 
 ## Features
 
-- Token signing with customizable options
-- Token verification with comprehensive validation
-- Support for various JWT algorithms (HS256, RS256, ES256, etc.)
-- Integration with Navios dependency injection system
-- Type-safe API with Zod schema validation
+- **Token Signing**: Create JWTs with customizable options (expiration, algorithm, claims, etc.)
+- **Token Verification**: Comprehensive validation with support for all standard JWT claims
+- **Multiple Algorithms**: Support for symmetric (HS256, HS384, HS512) and asymmetric (RS256, ES256, PS256, etc.) algorithms
+- **Dependency Injection**: Seamless integration with Navios DI system
+- **Type Safety**: Full TypeScript support with Zod schema validation
+- **Async Support**: Both synchronous and asynchronous APIs for flexible key management
+- **Dynamic Key Providers**: Support for dynamic secret/key resolution based on request context
 
-## Usage
+## Quick Start
 
 ### Basic Setup
 
 ```typescript
-import { inject } from '@navios/core'
 import { provideJwtService } from '@navios/jwt'
 
-const MyJwtService = provideJwtService({
+// Static configuration
+const JwtService = provideJwtService({
   secret: 'your-secret-key',
   signOptions: {
     expiresIn: '1h',
+    algorithm: 'HS256',
+  },
+  verifyOptions: {
+    algorithms: ['HS256'],
   },
-})
-// Or with factory
-const JwtService = provideJwtService(async () => {
-  const config = await inject(ConfigService)
-  return config.jwt
 })
 ```
 
-### Signing Tokens
+### Using with Dependency Injection
 
 ```typescript
-// Create a token
-import { Injectable, syncInject } from '@navios/core'
-//or to load without options
+import { Injectable, inject } from '@navios/core'
 import { JwtService } from '@navios/jwt'
 
-import { JwtService } from '../service/jwt.service.mjs'
-
 @Injectable()
 class AuthService {
-  jwtService = syncInject(JwtService)
+  jwtService = inject(JwtService)
+
+  async login(userId: string, role: string) {
+    // Sign a token
+    const token = this.jwtService.sign(
+      { userId, role },
+      { expiresIn: '1h' }
+    )
+    return { token }
+  }
 
-  async generateToken(userId: number, role: string) {
-    const token = await this.jwtService.signAsync({ userId, role })
-    return token
+  async validateToken(token: string) {
+    try {
+      // Verify and decode the token
+      const payload = this.jwtService.verify<{ userId: string; role: string }>(token)
+      return payload
+    } catch (error) {
+      if (error instanceof TokenExpiredError) {
+        throw new Error('Token expired')
+      }
+      throw error
+    }
   }
 }
 ```
 
+## Usage Examples
+
+### Async Configuration
+
+When you need to load configuration dynamically:
+
+```typescript
+import { provideJwtService } from '@navios/jwt'
+import { inject } from '@navios/core'
+
+const JwtService = provideJwtService(async () => {
+  const configService = await inject(ConfigService)
+  return {
+    secret: configService.jwt.secret,
+    signOptions: {
+      expiresIn: configService.jwt.expiresIn,
+      algorithm: configService.jwt.algorithm,
+    },
+  }
+})
+```
+
+### Asymmetric Keys (RS256)
+
+For applications using RSA or ECDSA keys:
+
+```typescript
+import { provideJwtService } from '@navios/jwt'
+import fs from 'fs'
+
+const JwtService = provideJwtService({
+  privateKey: fs.readFileSync('private.pem'),
+  publicKey: fs.readFileSync('public.pem'),
+  signOptions: {
+    algorithm: 'RS256',
+    expiresIn: '1h',
+  },
+  verifyOptions: {
+    algorithms: ['RS256'],
+  },
+})
+```
+
+### Dynamic Key Provider
+
+For applications that need to resolve keys dynamically based on the token:
+
+```typescript
+import { provideJwtService, RequestType } from '@navios/jwt'
+
+const JwtService = provideJwtService({
+  secretOrKeyProvider: (requestType, token, options) => {
+    if (requestType === RequestType.Sign) {
+      // Return signing key
+      return getSigningKey()
+    } else {
+      // Extract key ID from token and return corresponding public key
+      const decoded = jwt.decode(token, { complete: true })
+      const kid = decoded?.header?.kid
+      return getPublicKeyByKid(kid)
+    }
+  },
+})
+```
+
+### Signing Tokens
+
+```typescript
+// Synchronous signing
+const token = jwtService.sign(
+  { userId: '123', role: 'admin' },
+  { expiresIn: '1h' }
+)
+
+// Asynchronous signing (for async key providers)
+const token = await jwtService.signAsync(
+  { userId: '123', role: 'admin' },
+  { expiresIn: '1h' }
+)
+```
+
 ### Verifying Tokens
 
 ```typescript
+// Synchronous verification
 try {
-  // Verify and decode a token
-  const payload = await jwtService.verify(token)
-  console.log(payload) // { userId: 123, role: 'admin', iat: 1234567890, exp: 1234571490 }
+  const payload = jwtService.verify<{ userId: string; role: string }>(token)
+  console.log(payload.userId) // '123'
 } catch (error) {
-  // Handle verification errors
   if (error instanceof TokenExpiredError) {
     console.error('Token expired')
   } else if (error instanceof JsonWebTokenError) {
     console.error('Invalid token')
   }
 }
+
+// Asynchronous verification (for async key providers)
+try {
+  const payload = await jwtService.verifyAsync<{ userId: string }>(token)
+  console.log(payload.userId)
+} catch (error) {
+  // Handle errors
+}
+```
+
+### Decoding Without Verification
+
+```typescript
+// Decode without verification (use with caution)
+const payload = jwtService.decode<{ userId: string }>(token)
+if (payload) {
+  console.log(payload.userId)
+}
 ```
 
 ## API Reference
 
-### JwtServiceOptions
+### `JwtService`
+
+The main service class for JWT operations.
+
+#### Methods
+
+- **`sign(payload, options?)`**: Signs a JWT payload synchronously
+- **`signAsync(payload, options?)`**: Signs a JWT payload asynchronously
+- **`verify<T>(token, options?)`**: Verifies and decodes a JWT token synchronously
+- **`verifyAsync<T>(token, options?)`**: Verifies and decodes a JWT token asynchronously
+- **`decode<T>(token, options?)`**: Decodes a JWT token without verification
+
+### `provideJwtService(config)`
+
+Creates a JWT service provider for dependency injection.
+
+**Overloads:**
+- `provideJwtService(config: JwtServiceOptions)`: Static configuration
+- `provideJwtService(config: () => Promise<JwtServiceOptions>)`: Async factory configuration
+
+### `JwtServiceOptions`
 
 Configuration options for the JWT service:
 
 ```typescript
 interface JwtServiceOptions {
+  /** Default options for signing tokens */
   signOptions?: SignOptions
+  /** Default secret for symmetric algorithms (HS256, HS384, HS512) */
   secret?: string
+  /** Default public key for asymmetric algorithms (RS256, ES256, etc.) */
   publicKey?: string | Buffer
+  /** Default private key for asymmetric algorithms */
   privateKey?: Secret
+  /** Default options for verifying tokens */
   verifyOptions?: VerifyOptions
+  /** Optional function to dynamically resolve secrets/keys */
   secretOrKeyProvider?: (
     requestType: RequestType,
     token?: string,
@@ -102,13 +240,52 @@ interface JwtServiceOptions {
 }
 ```
 
-### Error Handling
+### Error Classes
 
 The library exports error classes from the underlying `jsonwebtoken` library:
 
-- `TokenExpiredError`: Thrown when the token is expired
-- `NotBeforeError`: Thrown when the token is not yet valid
-- `JsonWebTokenError`: Base class for all JWT errors
+- **`TokenExpiredError`**: Thrown when the token has expired
+  - `expiredAt`: Date when the token expired
+- **`NotBeforeError`**: Thrown when the token is not yet valid (nbf claim)
+  - `date`: Date when the token becomes valid
+- **`JsonWebTokenError`**: Base class for all JWT errors
+  - `message`: Error message describing the issue
+
+### Type Definitions
+
+- **`SignOptions`**: Options for signing tokens (algorithm, expiration, audience, issuer, etc.)
+- **`VerifyOptions`**: Options for verifying tokens (algorithms, audience, issuer, expiration handling, etc.)
+- **`JwtSignOptions`**: Extends `SignOptions` with `secret` and `privateKey` properties
+- **`JwtVerifyOptions`**: Extends `VerifyOptions` with `secret` and `publicKey` properties
+- **`RequestType`**: Enum for distinguishing sign vs verify operations (`Sign` | `Verify`)
+
+## Best Practices
+
+1. **Always use `verify()` or `verifyAsync()`** for production code. Never use `decode()` for security-sensitive operations.
+
+2. **Use async methods** when using `secretOrKeyProvider` that returns a Promise.
+
+3. **Specify allowed algorithms** in `verifyOptions` to prevent algorithm confusion attacks:
+   ```typescript
+   verifyOptions: {
+     algorithms: ['HS256', 'RS256'], // Explicitly allow only these algorithms
+   }
+   ```
+
+4. **Set appropriate expiration times** based on your security requirements:
+   ```typescript
+   signOptions: {
+     expiresIn: '15m', // Short-lived access tokens
+   }
+   ```
+
+5. **Use asymmetric keys** for distributed systems where public keys can be shared:
+   ```typescript
+   // Sign with private key
+   privateKey: fs.readFileSync('private.pem')
+   // Verify with public key (can be shared)
+   publicKey: fs.readFileSync('public.pem')
+   ```
 
 ## Contributing
 

package/dist/src/index.d.mts

@@ -2,7 +2,58 @@ import jwt from 'jsonwebtoken';
 export * from './options/jwt-service.options.mjs';
 export * from './jwt.service.mjs';
 export * from './jwt-service.provider.mjs';
+/**
+ * Error thrown when a JWT token has expired.
+ *
+ * This error is thrown by `verify()` and `verifyAsync()` when the token's
+ * expiration time (exp claim) has passed.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   jwtService.verify(token)
+ * } catch (error) {
+ *   if (error instanceof TokenExpiredError) {
+ *     console.error('Token expired at:', error.expiredAt)
+ *   }
+ * }
+ * ```
+ */
 export declare const TokenExpiredError: typeof jwt.TokenExpiredError;
+/**
+ * Error thrown when a JWT token is not yet valid.
+ *
+ * This error is thrown by `verify()` and `verifyAsync()` when the token's
+ * "not before" time (nbf claim) is in the future.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   jwtService.verify(token)
+ * } catch (error) {
+ *   if (error instanceof NotBeforeError) {
+ *     console.error('Token not valid until:', error.date)
+ *   }
+ * }
+ * ```
+ */
 export declare const NotBeforeError: typeof jwt.NotBeforeError;
+/**
+ * Base error class for JWT-related errors.
+ *
+ * This is the base class for all JWT errors including `TokenExpiredError`
+ * and `NotBeforeError`. It's thrown for invalid or malformed tokens.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   jwtService.verify(token)
+ * } catch (error) {
+ *   if (error instanceof JsonWebTokenError) {
+ *     console.error('JWT error:', error.message)
+ *   }
+ * }
+ * ```
+ */
 export declare const JsonWebTokenError: typeof jwt.JsonWebTokenError;
 //# sourceMappingURL=index.d.mts.map

package/dist/src/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/index.mts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,cAAc,CAAA;AAE9B,cAAc,mCAAmC,CAAA;AACjD,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,eAAO,MAAM,iBAAiB,8BAAwB,CAAA;AACtD,eAAO,MAAM,cAAc,2BAAqB,CAAA;AAChD,eAAO,MAAM,iBAAiB,8BAAwB,CAAA"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/index.mts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,cAAc,CAAA;AAE9B,cAAc,mCAAmC,CAAA;AACjD,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,8BAAwB,CAAA;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,2BAAqB,CAAA;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,8BAAwB,CAAA"}

package/dist/src/jwt-service.provider.d.mts

@@ -2,6 +2,56 @@ import type { BoundInjectionToken, FactoryInjectionToken } from '@navios/core';
 import type { JwtServiceOptions } from './options/jwt-service.options.mjs';
 import { JwtService } from './jwt.service.mjs';
 import { JwtServiceOptionsSchema } from './options/jwt-service.options.mjs';
+/**
+ * Creates a JWT service provider for dependency injection.
+ *
+ * This function creates an injection token that can be used to register and resolve
+ * `JwtService` instances in the Navios dependency injection container. It supports
+ * both static configuration and async factory functions for dynamic configuration.
+ *
+ * @param config - Static JWT service configuration options
+ * @returns A bound injection token that can be used with `inject()` or `syncInject()`
+ *
+ * @example
+ * ```ts
+ * // Static configuration
+ * const JwtService = provideJwtService({
+ *   secret: 'your-secret-key',
+ *   signOptions: { expiresIn: '1h' },
+ * })
+ *
+ * @Injectable()
+ * class AuthService {
+ *   jwtService = inject(JwtService)
+ * }
+ * ```
+ */
 export declare function provideJwtService(config: JwtServiceOptions): BoundInjectionToken<JwtService, typeof JwtServiceOptionsSchema>;
+/**
+ * Creates a JWT service provider with async configuration factory.
+ *
+ * Use this overload when you need to load configuration asynchronously, such as
+ * fetching secrets from a configuration service or environment variables.
+ *
+ * @param config - Async factory function that returns JWT service configuration
+ * @returns A factory injection token that resolves configuration asynchronously
+ *
+ * @example
+ * ```ts
+ * // Async configuration
+ * const JwtService = provideJwtService(async () => {
+ *   const configService = await inject(ConfigService)
+ *   return {
+ *     secret: configService.jwt.secret,
+ *     signOptions: { expiresIn: configService.jwt.expiresIn },
+ *   }
+ * })
+ *
+ * @Injectable()
+ * class AuthService {
+ *   jwtService = inject(JwtService)
+ * }
+ * ```
+ */
 export declare function provideJwtService(config: () => Promise<JwtServiceOptions>): FactoryInjectionToken<JwtService, typeof JwtServiceOptionsSchema>;
 //# sourceMappingURL=jwt-service.provider.d.mts.map

package/dist/src/jwt-service.provider.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt-service.provider.d.mts","sourceRoot":"","sources":["../../src/jwt-service.provider.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAI9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AAE1E,OAAO,EAAE,UAAU,EAAmB,MAAM,mBAAmB,CAAA;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAA;AAE3E,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,GACxB,mBAAmB,CAAC,UAAU,EAAE,OAAO,uBAAuB,CAAC,CAAA;AAClE,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,GACvC,qBAAqB,CAAC,UAAU,EAAE,OAAO,uBAAuB,CAAC,CAAA"}
+{"version":3,"file":"jwt-service.provider.d.mts","sourceRoot":"","sources":["../../src/jwt-service.provider.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAI9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AAE1E,OAAO,EAAE,UAAU,EAAmB,MAAM,mBAAmB,CAAA;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAA;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,GACxB,mBAAmB,CAAC,UAAU,EAAE,OAAO,uBAAuB,CAAC,CAAA;AAClE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,GACvC,qBAAqB,CAAC,UAAU,EAAE,OAAO,uBAAuB,CAAC,CAAA"}

package/dist/src/jwt.service.d.mts

@@ -2,6 +2,11 @@ import { InjectionToken } from '@navios/core';
 import jwt from 'jsonwebtoken';
 import type { JwtServiceOptions, JwtSignOptions, JwtVerifyOptions, SignOptions } from './options/jwt-service.options.mjs';
 import { RequestType } from './options/jwt-service.options.mjs';
+/**
+ * Injection token for JwtService.
+ *
+ * Used internally by the dependency injection system to register and resolve JwtService instances.
+ */
 export declare const JwtServiceToken: InjectionToken<unknown, import("zod/v4").ZodObject<{
     signOptions: import("zod/v4").ZodOptional<import("zod/v4").ZodObject<{
         algorithm: import("zod/v4").ZodOptional<import("zod/v4").ZodEnum<{
@@ -189,16 +194,181 @@ export declare const JwtServiceToken: InjectionToken<unknown, import("zod/v4").Z
         passphrase: import("zod/v4").ZodString;
     }, import("zod/v4/core").$strip>]>>]>>>;
 }, import("zod/v4/core").$strip>, true>;
+/**
+ * Service for signing, verifying, and decoding JSON Web Tokens (JWTs).
+ *
+ * This service provides a type-safe wrapper around the `jsonwebtoken` library with
+ * seamless integration into Navios's dependency injection system. It supports both
+ * symmetric (HS256, HS384, HS512) and asymmetric (RS256, ES256, etc.) algorithms.
+ *
+ * @example
+ * ```ts
+ * import { provideJwtService } from '@navios/jwt'
+ * import { inject } from '@navios/core'
+ *
+ * const JwtService = provideJwtService({
+ *   secret: 'your-secret-key',
+ *   signOptions: { expiresIn: '1h' },
+ * })
+ *
+ * @Injectable()
+ * class AuthService {
+ *   jwtService = inject(JwtService)
+ *
+ *   async login(userId: string) {
+ *     const token = this.jwtService.sign({ userId, role: 'user' })
+ *     return token
+ *   }
+ * }
+ * ```
+ */
 export declare class JwtService {
     private readonly options;
     logger: import("@navios/core").LoggerInstance;
+    /**
+     * Creates a new JwtService instance.
+     *
+     * @param options - Configuration options for the JWT service
+     */
     constructor(options?: JwtServiceOptions);
+    /**
+     * Signs a JWT payload synchronously.
+     *
+     * When the payload is a string, only `secret` and `privateKey` options are allowed.
+     * For object or Buffer payloads, all sign options are available.
+     *
+     * @param payload - The payload to sign. Can be a string, Buffer, or object.
+     * @param options - Signing options. When payload is a string, only `secret` and `privateKey` are allowed.
+     * @returns The signed JWT token as a string
+     * @throws {Error} If `secretOrKeyProvider` returns a Promise (use `signAsync` instead)
+     * @throws {Error} If payload is a string and invalid options are provided
+     *
+     * @example
+     * ```ts
+     * // Sign with object payload
+     * const token = jwtService.sign(
+     *   { userId: '123', role: 'admin' },
+     *   { expiresIn: '1h' }
+     * )
+     *
+     * // Sign with string payload (limited options)
+     * const token = jwtService.sign('payload-string', { secret: 'key' })
+     * ```
+     */
     sign(payload: string, options?: Omit<JwtSignOptions, keyof SignOptions>): string;
+    /**
+     * Signs a JWT payload synchronously.
+     *
+     * @param payload - The payload to sign. Can be a Buffer or object.
+     * @param options - Signing options including algorithm, expiration, etc.
+     * @returns The signed JWT token as a string
+     */
     sign(payload: Buffer | object, options?: JwtSignOptions): string;
+    /**
+     * Signs a JWT payload asynchronously.
+     *
+     * Use this method when `secretOrKeyProvider` returns a Promise or when you need
+     * to handle async key resolution. Supports the same payload types and options as `sign()`.
+     *
+     * @param payload - The payload to sign. Can be a string, Buffer, or object.
+     * @param options - Signing options. When payload is a string, only `secret` and `privateKey` are allowed.
+     * @returns A Promise that resolves to the signed JWT token as a string
+     * @throws {Error} If payload is a string and invalid options are provided
+     *
+     * @example
+     * ```ts
+     * // Sign with async key provider
+     * const token = await jwtService.signAsync(
+     *   { userId: '123' },
+     *   { expiresIn: '1h' }
+     * )
+     * ```
+     */
     signAsync(payload: string, options?: Omit<JwtSignOptions, keyof jwt.SignOptions>): Promise<string>;
+    /**
+     * Signs a JWT payload asynchronously.
+     *
+     * @param payload - The payload to sign. Can be a Buffer or object.
+     * @param options - Signing options including algorithm, expiration, etc.
+     * @returns A Promise that resolves to the signed JWT token as a string
+     */
     signAsync(payload: Buffer | object, options?: JwtSignOptions): Promise<string>;
+    /**
+     * Verifies and decodes a JWT token synchronously.
+     *
+     * This method validates the token's signature, expiration, and other claims
+     * according to the provided options. If verification fails, an error is thrown.
+     *
+     * @template T - The expected type of the decoded payload
+     * @param token - The JWT token string to verify
+     * @param options - Verification options including algorithms, audience, issuer, etc.
+     * @returns The decoded payload as type T
+     * @throws {TokenExpiredError} If the token has expired
+     * @throws {NotBeforeError} If the token is not yet valid (nbf claim)
+     * @throws {JsonWebTokenError} If the token is invalid or malformed
+     * @throws {Error} If `secretOrKeyProvider` returns a Promise (use `verifyAsync` instead)
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const payload = jwtService.verify<{ userId: string; role: string }>(token)
+     *   console.log(payload.userId) // '123'
+     * } catch (error) {
+     *   if (error instanceof TokenExpiredError) {
+     *     console.error('Token expired')
+     *   }
+     * }
+     * ```
+     */
     verify<T extends object = any>(token: string, options?: JwtVerifyOptions): T;
+    /**
+     * Verifies and decodes a JWT token asynchronously.
+     *
+     * Use this method when `secretOrKeyProvider` returns a Promise or when you need
+     * to handle async key resolution. Provides the same validation as `verify()`.
+     *
+     * @template T - The expected type of the decoded payload
+     * @param token - The JWT token string to verify
+     * @param options - Verification options including algorithms, audience, issuer, etc.
+     * @returns A Promise that resolves to the decoded payload as type T
+     * @throws {TokenExpiredError} If the token has expired
+     * @throws {NotBeforeError} If the token is not yet valid (nbf claim)
+     * @throws {JsonWebTokenError} If the token is invalid or malformed
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const payload = await jwtService.verifyAsync<{ userId: string }>(token)
+     *   console.log(payload.userId)
+     * } catch (error) {
+     *   if (error instanceof TokenExpiredError) {
+     *     console.error('Token expired')
+     *   }
+     * }
+     * ```
+     */
     verifyAsync<T extends object = any>(token: string, options?: JwtVerifyOptions): Promise<T>;
+    /**
+     * Decodes a JWT token without verification.
+     *
+     * This method decodes the token without validating its signature or claims.
+     * Use this only when you need to inspect the token contents without verification.
+     * For secure token validation, use `verify()` or `verifyAsync()` instead.
+     *
+     * @template T - The expected type of the decoded payload
+     * @param token - The JWT token string to decode
+     * @param options - Decode options (complete, json, etc.)
+     * @returns The decoded payload as type T, or null if decoding fails
+     *
+     * @example
+     * ```ts
+     * // Decode without verification (not recommended for production)
+     * const payload = jwtService.decode<{ userId: string }>(token)
+     * if (payload) {
+     *   console.log(payload.userId)
+     * }
+     * ```
+     */
     decode<T = any>(token: string, options?: jwt.DecodeOptions): T;
     private mergeJwtOptions;
     private getSecretKey;

package/dist/src/jwt.service.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.service.d.mts","sourceRoot":"","sources":["../../src/jwt.service.mts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,cAAc,EAAU,MAAM,cAAc,CAAA;AAEzE,OAAO,GAAG,MAAM,cAAc,CAAA;AAE9B,OAAO,KAAK,EAEV,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,WAAW,EAEZ,MAAM,mCAAmC,CAAA;AAE1C,OAAO,EAEL,WAAW,EACZ,MAAM,mCAAmC,CAAA;AAE1C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCAG3B,CAAA;AAED,qBAGa,UAAU;IAKT,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,MAAM,wCAEJ;gBAE2B,OAAO,GAAE,iBAAsB;IAE5D,IAAI,CACF,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,WAAW,CAAC,GAChD,MAAM;IACT,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM;IAuChE,SAAS,CACP,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,CAAC,WAAW,CAAC,GACpD,OAAO,CAAC,MAAM,CAAC;IAClB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC9E,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,GAAG,EAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,CAAC;IAqBJ,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,GAAG,EAChC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC;IAsBb,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,aAAa,GAAG,CAAC;IAI9D,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,YAAY;CAkBrB"}
+{"version":3,"file":"jwt.service.d.mts","sourceRoot":"","sources":["../../src/jwt.service.mts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,cAAc,EAAU,MAAM,cAAc,CAAA;AAEzE,OAAO,GAAG,MAAM,cAAc,CAAA;AAE9B,OAAO,KAAK,EAEV,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,WAAW,EAEZ,MAAM,mCAAmC,CAAA;AAE1C,OAAO,EAEL,WAAW,EACZ,MAAM,mCAAmC,CAAA;AAE1C;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCAG3B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAGa,UAAU;IAUT,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,MAAM,wCAEJ;IAEF;;;;OAIG;gBAC0B,OAAO,GAAE,iBAAsB;IAE5D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,IAAI,CACF,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,WAAW,CAAC,GAChD,MAAM;IACT;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM;IAuChE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,CAAC,WAAW,CAAC,GACpD,OAAO,CAAC,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC9E;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,GAAG,EAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,CAAC;IAqBJ;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,GAAG,EAChC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC;IAsBb;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,aAAa,GAAG,CAAC;IAI9D,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,YAAY;CAkBrB"}