@hkdigital/lib-core 0.4.12 → 0.4.14

package/README.md

@@ -35,6 +35,9 @@ pnpm add @steeze-ui/heroicons
 # Logging
 pnpm add pino pino-pretty
 
+# JWT authentication (if using auth features)
+pnpm add jsonwebtoken
+
 # Linting
 pnpm add @eslint/js eslint-plugin-import
 
@@ -45,7 +48,7 @@ pnpm add vite-imagetools
 **For other libraries**, install as dev dependencies and declare as peer dependencies:
 ```bash
 # Install as dev dependencies and peer dependencies
-pnpm add -D --save-peer @sveltejs/kit svelte svelte-preprocess runed valibot @skeletonlabs/skeleton @steeze-ui/heroicons pino pino-pretty @eslint/js eslint-plugin-import vite-imagetools
+pnpm add -D --save-peer @sveltejs/kit svelte svelte-preprocess runed valibot @skeletonlabs/skeleton @steeze-ui/heroicons pino pino-pretty jsonwebtoken @eslint/js eslint-plugin-import vite-imagetools
 ```
 
 ### Design System & Configuration

package/dist/auth/errors.d.ts

@@ -1 +1 @@
-export * from "./errors/jwt.js";
+export * from "./jwt/errors.js";

package/dist/auth/errors.js

@@ -1 +1 @@
-export * from './errors/jwt.js';
+export * from './jwt/errors.js';

package/dist/auth/jwt/constants.d.ts

@@ -0,0 +1,6 @@
+export const JWT_DEFAULT_EXPIRES_IN: "30h";
+export const JWT_NEVER_EXPIRES: any;
+export const DEFAULT_ALGORITHM: "HS512";
+export namespace VERIFY_OPTIONS {
+    let algorithms: string[];
+}

package/dist/auth/jwt/constants.js

@@ -0,0 +1,13 @@
+export const JWT_DEFAULT_EXPIRES_IN = '30h';
+export const JWT_NEVER_EXPIRES = null;
+
+export const DEFAULT_ALGORITHM = 'HS512';
+
+export const VERIFY_OPTIONS =
+  {
+    //
+    // Never forget to make this explicit to
+    // prevent signature stripping attacks
+    //
+    algorithms: [ DEFAULT_ALGORITHM ]
+  };

package/dist/auth/jwt/errors.d.ts

@@ -0,0 +1,39 @@
+export class SecretKeyError extends Error {
+}
+export class TokenExpiredError extends Error {
+    /**
+     * @param {string} message - Error message
+     * @param {Date|{expiredAt?: Date}} [details] - When token expired or details object
+     * @param {Error} [cause] - Original error
+     */
+    constructor(message: string, details?: Date | {
+        expiredAt?: Date;
+    }, cause?: Error);
+    expiredAt: Date;
+    cause: Error;
+}
+export class JsonWebTokenError extends Error {
+    /**
+     * @param {string} message - Error message
+     * @param {Error|{inner?: Error}} [details] - Inner error or details object
+     * @param {Error} [cause] - Original error
+     */
+    constructor(message: string, details?: Error | {
+        inner?: Error;
+    }, cause?: Error);
+    inner: Error;
+    cause: Error;
+}
+export class InvalidSignatureError extends JsonWebTokenError {
+}
+export class NotBeforeError extends JsonWebTokenError {
+    /**
+     * @param {string} message - Error message
+     * @param {Date|{date?: Date}} [details] - Date when token becomes valid or details object
+     * @param {Error} [cause] - Original error
+     */
+    constructor(message: string, details?: Date | {
+        date?: Date;
+    }, cause?: Error);
+    date: Date;
+}

package/dist/auth/jwt/errors.js

@@ -0,0 +1,74 @@
+export class SecretKeyError extends Error {}
+
+export class TokenExpiredError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {Date|{expiredAt?: Date}} [details] - When token expired or details object
+   * @param {Error} [cause] - Original error
+   */
+  constructor(message, details, cause) {
+    super(message);
+    this.name = 'TokenExpiredError';
+    
+    // Handle both Date and object formats for details
+    if (details instanceof Date) {
+      this.expiredAt = details;
+    } else {
+      this.expiredAt = details?.expiredAt ?? null;
+    }
+    
+    this.cause = cause ?? null;
+  }
+}
+
+export class JsonWebTokenError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {Error|{inner?: Error}} [details] - Inner error or details object
+   * @param {Error} [cause] - Original error
+   */
+  constructor(message, details, cause) {
+    super(message);
+    this.name = 'JsonWebTokenError';
+    
+    // Handle both Error and object formats for details
+    if (details instanceof Error) {
+      this.inner = details;
+    } else {
+      this.inner = details?.inner ?? null;
+    }
+    
+    this.cause = cause ?? null;
+  }
+}
+
+export class InvalidSignatureError extends JsonWebTokenError {
+  /**
+   * @param {string} message - Error message
+   * @param {Error|{inner?: Error}} [details] - Inner error or details object
+   * @param {Error} [cause] - Original error
+   */
+  constructor(message, details, cause) {
+    super(message, details, cause);
+    this.name = 'InvalidSignatureError';
+  }
+}
+
+export class NotBeforeError extends JsonWebTokenError {
+  /**
+   * @param {string} message - Error message
+   * @param {Date|{date?: Date}} [details] - Date when token becomes valid or details object
+   * @param {Error} [cause] - Original error
+   */
+  constructor(message, details, cause) {
+    super(message, null, cause);
+    this.name = 'NotBeforeError';
+    
+    // Handle both Date and object formats for details
+    if (details instanceof Date) {
+      this.date = details;
+    } else {
+      this.date = details?.date ?? null;
+    }
+  }
+}

package/dist/auth/jwt/generators.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generate a secret key with the specified number of bytes
+ * - The default length is 64 bytes, which is 512 bits, which is a nice secret
+ *   key length for the HS512 algorithm
+ *
+ * @returns {string} a base64 encoded secret key string
+ */
+export function generateSecretKeyBase64(numberOfBytes?: number): string;
+/**
+ * Create a string that can be used as secret key for HMAC
+ * - An HMAC is an Hash based Message Authentication Code
+ *
+ * - The formula for calculating a HMAC is:
+ *
+ *   HMAC = hashFunc(secret key + message)
+ *
+ * - This function generates a long random secret
+ *
+ * - The secret key is quite long because long keys are more likely to
+ *   resistent brute force attacks
+ *
+ * - The returned secret is a base58 encoded string
+ *
+ * @note The standard javascript random generator is used. For more secure
+ *       secret keys consider using crypto
+ *
+ * @returns {string} generated secret, formatted as base 58 string
+ */
+export function generateSecretKeyForHmacBase58(): string;

package/dist/auth/jwt/generators.js

@@ -0,0 +1,53 @@
+/**
+ * JWT secret key generation utilities
+ *
+ * @description
+ * This module provides utilities for generating cryptographically secure
+ * secret keys for JWT signing and verification.
+ */
+
+import { base58fromNumber, bytesToNumber } from '../../util/bases.js';
+import { randomBytes, randomBytesBase64 } from '../../util/random.js';
+
+/**
+ * Generate a secret key with the specified number of bytes
+ * - The default length is 64 bytes, which is 512 bits, which is a nice secret
+ *   key length for the HS512 algorithm
+ *
+ * @returns {string} a base64 encoded secret key string
+ */
+export function generateSecretKeyBase64( numberOfBytes=64 )
+{
+  return randomBytesBase64( numberOfBytes );
+}
+
+/**
+ * Create a string that can be used as secret key for HMAC
+ * - An HMAC is an Hash based Message Authentication Code
+ *
+ * - The formula for calculating a HMAC is:
+ *
+ *   HMAC = hashFunc(secret key + message)
+ *
+ * - This function generates a long random secret
+ *
+ * - The secret key is quite long because long keys are more likely to
+ *   resistent brute force attacks
+ *
+ * - The returned secret is a base58 encoded string
+ *
+ * @note The standard javascript random generator is used. For more secure
+ *       secret keys consider using crypto
+ *
+ * @returns {string} generated secret, formatted as base 58 string
+ */
+export function generateSecretKeyForHmacBase58()
+{
+  const numberOfBytes = 64;
+
+  const bytes = randomBytes( numberOfBytes );
+
+  const numericValue = bytesToNumber( bytes );
+
+  return base58fromNumber( numericValue );
+}

package/dist/auth/jwt/typedef.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Standard JWT claims (RFC 7519)
+ */
+export type JwtStandardClaims = {
+    /**
+     * - Issuer
+     */
+    iss?: string;
+    /**
+     * - Subject
+     */
+    sub?: string;
+    /**
+     * - Audience
+     */
+    aud?: string | string[];
+    /**
+     * - Expiration time (seconds since epoch)
+     */
+    exp?: number;
+    /**
+     * - Not before (seconds since epoch)
+     */
+    nbf?: number;
+    /**
+     * - Issued at (seconds since epoch)
+     */
+    iat?: number;
+    /**
+     * - JWT ID
+     */
+    jti?: string;
+};
+/**
+ * JWT payload - standard claims plus any custom data
+ */
+export type JwtPayload = JwtStandardClaims & Record<string, any>;
+/**
+ * JWT signing options
+ */
+export type SignOptions = {
+    /**
+     * - Signing algorithm (HS256, RS256, etc.)
+     */
+    algorithm?: string;
+    /**
+     * - Expiration time ('1h', 3600, etc.)
+     */
+    expiresIn?: string | number;
+    /**
+     * - Not valid before time
+     */
+    notBefore?: string | number;
+    /**
+     * - Audience claim
+     */
+    audience?: string | string[];
+    /**
+     * - Issuer claim
+     */
+    issuer?: string;
+    /**
+     * - JWT ID claim
+     */
+    jwtid?: string;
+    /**
+     * - Subject claim
+     */
+    subject?: string;
+    /**
+     * - Skip iat claim
+     */
+    noTimestamp?: boolean;
+    /**
+     * - Additional header claims
+     */
+    header?: any;
+    /**
+     * - Key ID header claim
+     */
+    keyid?: string;
+    /**
+     * - Modify payload object directly
+     */
+    mutatePayload?: boolean;
+};
+/**
+ * JWT verification options
+ */
+export type VerifyOptions = {
+    /**
+     * - Allowed algorithms
+     */
+    algorithms?: string[];
+    /**
+     * - Expected audience
+     */
+    audience?: string | string[];
+    /**
+     * - Return object with payload and header
+     */
+    complete?: boolean;
+    /**
+     * - Expected issuer
+     */
+    issuer?: string;
+    /**
+     * - Skip expiration validation
+     */
+    ignoreExpiration?: boolean;
+    /**
+     * - Skip notBefore validation
+     */
+    ignoreNotBefore?: boolean;
+    /**
+     * - Expected subject
+     */
+    subject?: string;
+    /**
+     * - Clock tolerance in seconds
+     */
+    clockTolerance?: number;
+    /**
+     * - Maximum token age in seconds
+     */
+    maxAge?: number;
+    /**
+     * - Current time override (seconds)
+     */
+    clockTimestamp?: number;
+    /**
+     * - Expected nonce claim
+     */
+    nonce?: string;
+};
+/**
+ * JWT secret types
+ */
+export type Secret = string | Buffer | {
+    key: string | Buffer;
+    passphrase: string;
+};
+/**
+ * Decoded JWT result
+ */
+export type JwtDecoded = {
+    /**
+     * - The decoded payload
+     */
+    payload: JwtPayload;
+    /**
+     * - The decoded header
+     */
+    header: any;
+    /**
+     * - The signature
+     */
+    signature: string;
+};

package/dist/auth/jwt/typedef.js

@@ -0,0 +1,72 @@
+/**
+ * JWT type definitions
+ *
+ * @description
+ * Type definitions for JWT operations, based on jsonwebtoken library types.
+ */
+
+/**
+ * Standard JWT claims (RFC 7519)
+ * @typedef {Object} JwtStandardClaims
+ * @property {string} [iss] - Issuer
+ * @property {string} [sub] - Subject  
+ * @property {string|string[]} [aud] - Audience
+ * @property {number} [exp] - Expiration time (seconds since epoch)
+ * @property {number} [nbf] - Not before (seconds since epoch)
+ * @property {number} [iat] - Issued at (seconds since epoch)
+ * @property {string} [jti] - JWT ID
+ */
+
+/**
+ * JWT payload - standard claims plus any custom data
+ * @typedef {JwtStandardClaims & Record<string, any>} JwtPayload
+ */
+
+/**
+ * JWT signing options
+ * @typedef {Object} SignOptions
+ * @property {string} [algorithm] - Signing algorithm (HS256, RS256, etc.)
+ * @property {string|number} [expiresIn] - Expiration time ('1h', 3600, etc.)
+ * @property {string|number} [notBefore] - Not valid before time
+ * @property {string|string[]} [audience] - Audience claim
+ * @property {string} [issuer] - Issuer claim
+ * @property {string} [jwtid] - JWT ID claim
+ * @property {string} [subject] - Subject claim
+ * @property {boolean} [noTimestamp] - Skip iat claim
+ * @property {Object} [header] - Additional header claims
+ * @property {string} [keyid] - Key ID header claim
+ * @property {boolean} [mutatePayload] - Modify payload object directly
+ */
+
+/**
+ * JWT verification options
+ * @typedef {Object} VerifyOptions
+ * @property {string[]} [algorithms] - Allowed algorithms
+ * @property {string|string[]} [audience] - Expected audience
+ * @property {boolean} [complete] - Return object with payload and header
+ * @property {string} [issuer] - Expected issuer
+ * @property {boolean} [ignoreExpiration] - Skip expiration validation
+ * @property {boolean} [ignoreNotBefore] - Skip notBefore validation
+ * @property {string} [subject] - Expected subject
+ * @property {number} [clockTolerance] - Clock tolerance in seconds
+ * @property {number} [maxAge] - Maximum token age in seconds
+ * @property {number} [clockTimestamp] - Current time override (seconds)
+ * @property {string} [nonce] - Expected nonce claim
+ */
+
+/**
+ * JWT secret types
+ * @typedef {string|Buffer|{key: string|Buffer, passphrase: string}} Secret
+ */
+
+
+/**
+ * Decoded JWT result
+ * @typedef {Object} JwtDecoded
+ * @property {JwtPayload} payload - The decoded payload
+ * @property {Object} header - The decoded header
+ * @property {string} signature - The signature
+ */
+
+// Export types for use in JSDoc
+export {};

package/dist/auth/jwt/util.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Create a JSON Web Token (JWT)
+ * - Stringifies the claims as JSON object
+ * - Encodes the options
+ * - Calculates a Message Authentication Code (MAC)
+ *   (by default a Hash Based Authentication Code (HMAC) will be used: HS512)
+ * - Combines the parts into a JWT string
+ *
+ * @param {import('./typedef.js').JwtPayload} claims - JWT payload/claims
+ * @param {import('./typedef.js').Secret} secretOrPrivateKey
+ *   Secret or private key that is used by the MAC calculation algorithm
+ *
+ *   - To generate a secret for a Hash based Authentication Code (HMAC):
+ *     use a function like `generateSecretKeyForHmacBase58()`.
+ *
+ *   - For algorithms that use asymmetric keys, the secret is the private key
+ *     of the key pair.
+ *
+ * @param {import('./typedef.js').SignOptions} [options] - JWT signing options
+ *
+ * For more options:
+ * @see https://github.com/auth0/node-jsonwebtoken
+ *
+ * @returns {string} JsonWebToken
+ */
+export function sign(claims: import("./typedef.js").JwtPayload, secretOrPrivateKey: import("./typedef.js").Secret, options?: import("./typedef.js").SignOptions): string;
+/**
+ * Decode and verify a JWT token
+ * - Forces the use of the algorithm specified in VERIFY_OPTIONS
+ *
+ * @param {string} token - A JWT token
+ * @param {import('./typedef.js').Secret} secretOrPrivateKey
+ *   The secret of private key to be used for decoding
+ * @param {import('./typedef.js').VerifyOptions} [options=VERIFY_OPTIONS] - verify / decode options
+ *
+ * @returns {import('./typedef.js').JwtPayload} claims - The decoded JWT payload
+ */
+export function verify(token: string, secretOrPrivateKey: import("./typedef.js").Secret, options?: import("./typedef.js").VerifyOptions): import("./typedef.js").JwtPayload;
+/**
+ * Casts jsonwebtoken library errors to internal error types
+ * @param {Error} error - The original jsonwebtoken error
+ * @returns {Error} - The corresponding internal error
+ */
+export function castJwtError(error: Error): Error;

package/dist/auth/jwt/util.js

@@ -0,0 +1,150 @@
+/**
+ * JWT utility functions
+ *
+ * @description
+ * This module provides utility functions for JWT operations including 
+ * sign, verify and error casting.
+ */
+
+import jwt from 'jsonwebtoken';
+
+import {
+  TokenExpiredError as JwtTokenExpiredError,
+  JsonWebTokenError as JwtJsonWebTokenError,
+  NotBeforeError as JwtNotBeforeError
+} from 'jsonwebtoken';
+
+import * as expect from '../../util/expect.js';
+
+import {
+  JWT_DEFAULT_EXPIRES_IN,
+  DEFAULT_ALGORITHM,
+  VERIFY_OPTIONS 
+} from './constants.js';
+
+import {
+  TokenExpiredError,
+  JsonWebTokenError,
+  InvalidSignatureError,
+  NotBeforeError
+} from './errors.js';
+
+/**
+ * Create a JSON Web Token (JWT)
+ * - Stringifies the claims as JSON object
+ * - Encodes the options
+ * - Calculates a Message Authentication Code (MAC)
+ *   (by default a Hash Based Authentication Code (HMAC) will be used: HS512)
+ * - Combines the parts into a JWT string
+ *
+ * @param {import('./typedef.js').JwtPayload} claims - JWT payload/claims
+ * @param {import('./typedef.js').Secret} secretOrPrivateKey
+ *   Secret or private key that is used by the MAC calculation algorithm
+ *
+ *   - To generate a secret for a Hash based Authentication Code (HMAC):
+ *     use a function like `generateSecretKeyForHmacBase58()`.
+ *
+ *   - For algorithms that use asymmetric keys, the secret is the private key
+ *     of the key pair.
+ *
+ * @param {import('./typedef.js').SignOptions} [options] - JWT signing options
+ *
+ * For more options:
+ * @see https://github.com/auth0/node-jsonwebtoken
+ *
+ * @returns {string} JsonWebToken
+ */
+export function sign(
+  claims,
+  secretOrPrivateKey,
+  options={} )
+{
+  expect.object( claims );
+  expect.defined( secretOrPrivateKey );
+
+  if( options )
+  {
+    expect.object( options );
+  }
+  else {
+    options = {};
+  }
+
+  if( !('algorithm' in options) )
+  {
+    options.algorithm = DEFAULT_ALGORITHM;
+  }
+
+  if( !('expiresIn' in options) )
+  {
+    options.expiresIn = JWT_DEFAULT_EXPIRES_IN;
+  }
+  else if( !options.expiresIn )
+  {
+    delete options.expiresIn;
+  }
+
+  // @ts-ignore
+  return jwt.sign( claims, secretOrPrivateKey, options );
+}
+
+/**
+ * Decode and verify a JWT token
+ * - Forces the use of the algorithm specified in VERIFY_OPTIONS
+ *
+ * @param {string} token - A JWT token
+ * @param {import('./typedef.js').Secret} secretOrPrivateKey
+ *   The secret of private key to be used for decoding
+ * @param {import('./typedef.js').VerifyOptions} [options=VERIFY_OPTIONS] - verify / decode options
+ *
+ * @returns {import('./typedef.js').JwtPayload} claims - The decoded JWT payload
+ */
+export function verify( token, secretOrPrivateKey, options=VERIFY_OPTIONS )
+{
+  expect.notEmptyString( token );
+  expect.defined( secretOrPrivateKey );
+
+  if( !('algorithms' in options) )
+  {
+    options.algorithms = VERIFY_OPTIONS.algorithms;
+  }
+
+  try {
+    // @ts-ignore
+    const decoded = jwt.verify( token, secretOrPrivateKey, options );
+
+    return decoded;
+  }
+  catch( e )
+  {
+    //
+    // Cast internal jsonwebtoken errors to Error types defined in this lib
+    //
+    throw castJwtError(e);
+  }
+}
+
+/**
+ * Casts jsonwebtoken library errors to internal error types
+ * @param {Error} error - The original jsonwebtoken error
+ * @returns {Error} - The corresponding internal error
+ */
+export function castJwtError(error) {
+  if (error instanceof JwtTokenExpiredError) {
+    return new TokenExpiredError(error.message, error.expiredAt, error);
+  }
+  
+  if (error instanceof JwtNotBeforeError) {
+    return new NotBeforeError(error.message, error.date, error);
+  }
+  
+  if (error instanceof JwtJsonWebTokenError) {
+    if (error.message === 'invalid signature') {
+      return new InvalidSignatureError(error.message, error, error);
+    }
+    return new JsonWebTokenError(error.message, error, error);
+  }
+  
+  // Return original error if not a known JWT error
+  return error;
+}

package/dist/auth/jwt.d.ts

@@ -0,0 +1,3 @@
+export * from "./jwt/generators.js";
+export * from "./jwt/errors.js";
+export * from "./jwt/constants.js";

package/dist/auth/jwt.js

@@ -0,0 +1,12 @@
+/**
+ * JWT utilities main export
+ *
+ * @description
+ * This module provides a clean API for JWT operations including signing,
+ * verifying tokens, and generating secret keys.
+ */
+
+export * from './jwt/core.js';
+export * from './jwt/generators.js';
+export * from './jwt/errors.js';
+export * from './jwt/constants.js';