@navios/jwt 0.5.0 → 0.7.0

package/src/options/jwt-service.options.mts

@@ -2,11 +2,24 @@ import type { Secret as JwtSecret } from 'jsonwebtoken'
 
 import { z } from 'zod/v4'
 
+/**
+ * Request type for secret or key provider functions.
+ *
+ * Used to distinguish between signing and verification operations when
+ * dynamically resolving secrets or keys.
+ */
 export enum RequestType {
+  /** Request is for signing a token */
   Sign = 'Sign',
+  /** Request is for verifying a token */
   Verify = 'Verify',
 }
 
+/**
+ * Supported JWT algorithms.
+ *
+ * Includes symmetric (HMAC) and asymmetric (RSA, ECDSA, EdDSA) algorithms.
+ */
 export const AlgorithmType = z.enum([
   'HS256',
   'HS384',
@@ -23,6 +36,11 @@ export const AlgorithmType = z.enum([
   'none',
 ])
 
+/**
+ * JWT header schema.
+ *
+ * Defines the structure of the JWT header with standard claims.
+ */
 export const JwtHeaderSchema = z.object({
   alg: AlgorithmType.or(z.string()),
   typ: z.string().optional(),
@@ -36,8 +54,19 @@ export const JwtHeaderSchema = z.object({
   x5c: z.union([z.string(), z.array(z.string())]).optional(),
 })
 
+/**
+ * JWT header type.
+ *
+ * Contains algorithm, type, and optional header claims.
+ */
 export type JwtHeader = z.infer<typeof JwtHeaderSchema>
 
+/**
+ * Schema for JWT signing options.
+ *
+ * Defines all available options for signing tokens including algorithm,
+ * expiration, audience, issuer, and other standard JWT claims.
+ */
 export const SignOptionsSchema = z.object({
   algorithm: AlgorithmType.optional(),
   keyid: z.string().optional(),
@@ -61,8 +90,19 @@ export const SignOptionsSchema = z.object({
   allowInvalidAsymmetricKeyTypes: z.boolean().optional(),
 })
 
+/**
+ * Options for signing JWT tokens.
+ *
+ * @see SignOptionsSchema for the complete schema definition
+ */
 export type SignOptions = z.infer<typeof SignOptionsSchema>
 
+/**
+ * Schema for JWT verification options.
+ *
+ * Defines all available options for verifying tokens including allowed
+ * algorithms, audience, issuer, expiration handling, and other validation rules.
+ */
 export const VerifyOptionsSchema = z.object({
   algorithms: AlgorithmType.array().optional(),
   audience: z
@@ -85,8 +125,18 @@ export const VerifyOptionsSchema = z.object({
   allowInvalidAsymmetricKeyTypes: z.boolean().optional(),
 })
 
+/**
+ * Options for verifying JWT tokens.
+ *
+ * @see VerifyOptionsSchema for the complete schema definition
+ */
 export type VerifyOptions = z.infer<typeof VerifyOptionsSchema>
 
+/**
+ * Schema for JWT secret/key types.
+ *
+ * Supports string secrets, Buffer objects, and key objects with passphrases.
+ */
 export const SecretSchema = z.union([
   z.string(),
   z.instanceof(Buffer),
@@ -101,6 +151,11 @@ export const SecretSchema = z.union([
   }),
 ])
 
+/**
+ * Secret or key type for JWT operations.
+ *
+ * Can be a string, Buffer, or an object with key and optional passphrase.
+ */
 export type Secret = z.infer<typeof SecretSchema>
 
 export const JwtServiceOptionsSchema = z.object({
@@ -121,16 +176,67 @@ export const JwtServiceOptionsSchema = z.object({
     .optional(),
 })
 
+/**
+ * Configuration options for the JWT service.
+ *
+ * @property signOptions - Default options for signing tokens
+ * @property secret - Default secret for symmetric algorithms (HS256, HS384, HS512)
+ * @property publicKey - Default public key for asymmetric algorithms (RS256, ES256, etc.)
+ * @property privateKey - Default private key for asymmetric algorithms
+ * @property verifyOptions - Default options for verifying tokens
+ * @property secretOrKeyProvider - Optional function to dynamically resolve secrets/keys
+ *
+ * @example
+ * ```ts
+ * const options: JwtServiceOptions = {
+ *   secret: 'your-secret-key',
+ *   signOptions: {
+ *     expiresIn: '1h',
+ *     algorithm: 'HS256',
+ *   },
+ *   verifyOptions: {
+ *     algorithms: ['HS256'],
+ *   },
+ * }
+ * ```
+ */
 export type JwtServiceOptions = z.infer<typeof JwtServiceOptionsSchema>
 
+/**
+ * Options for signing JWT tokens.
+ *
+ * Extends `SignOptions` with additional properties for specifying
+ * the secret or private key to use for signing.
+ *
+ * @property secret - Secret key for symmetric algorithms (overrides service default)
+ * @property privateKey - Private key for asymmetric algorithms (overrides service default)
+ */
 export interface JwtSignOptions extends SignOptions {
+  /** Secret key for symmetric algorithms */
   secret?: string | Buffer
+  /** Private key for asymmetric algorithms */
   privateKey?: Secret
 }
 
+/**
+ * Options for verifying JWT tokens.
+ *
+ * Extends `VerifyOptions` with additional properties for specifying
+ * the secret or public key to use for verification.
+ *
+ * @property secret - Secret key for symmetric algorithms (overrides service default)
+ * @property publicKey - Public key for asymmetric algorithms (overrides service default)
+ */
 export interface JwtVerifyOptions extends VerifyOptions {
+  /** Secret key for symmetric algorithms */
   secret?: string | Buffer
+  /** Public key for asymmetric algorithms */
   publicKey?: string | Buffer
 }
 
+/**
+ * Result type for secret/key resolution.
+ *
+ * Represents the possible return types from secret or key provider functions.
+ */
 export type GetSecretKeyResult = string | Buffer | JwtSecret

package/tsdown.config.mts

@@ -0,0 +1,33 @@
+import { withFilter } from 'rolldown/filter'
+import { defineConfig } from 'tsdown'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  entry: ['src/index.mts'],
+  outDir: 'lib',
+  format: ['esm', 'cjs'],
+  clean: true,
+  treeshake: true,
+  sourcemap: true,
+  platform: 'node',
+  dts: true,
+  target: 'es2022',
+  plugins: [
+    withFilter(
+      swc.rolldown({
+        jsc: {
+          target: 'es2022',
+          parser: {
+            syntax: 'typescript',
+            decorators: true,
+          },
+          transform: {
+            decoratorVersion: '2022-03',
+          },
+        },
+      }),
+      // Only run this transform if the file contains a decorator.
+      { transform: { code: '@' } },
+    ),
+  ],
+})