@best-skn/elysia-helmet v1.0.1

SKN Elysia.js Helmet

TypeScript

Introduction:

A comprehensive security middleware for Elysia.js applications that helps to secure your apps by setting various HTTP headers

This library is originally created by aashahin. Total logic has been written by him. His original repository is Elysia Helmet. I just exported some types so that it can be imported in separate files while using this library and also added an object holding some readonly properties related to security configurations

I created this library so that I can manage it myself so that I don't have to rely on aashahin

Features:

• 🛡️ Content Security Policy (CSP)
• 🔒 X-Frame-Options protection
• 🚫 XSS Protection
• 🌐 DNS Prefetch Control
• 📜 Referrer Policy
• 🔑 Permissions Policy
• 🔐 HTTP Strict Transport Security (HSTS)
• 🌍 Cross-Origin Resource Policy (CORP)
• 🚪 Cross-Origin Opener Policy (COOP)
• 📝 Report-To header configuration
• ✨ Custom headers support

Details:

ReportToConfig Interface

• Configuration interface for Report-To header
• For usage instruction, see Usage section

CSPConfig Interface

• Configuration interface for Content Security Policy
• For usage instruction, see Usage section

HSTSConfig Interface

• Configuration inerface for HTTP Strict Transport Security
• For usage instruction, see Usage section

SecurityConfig Interface

• Configuration interface for Security Headers
• For usage instruction, see Usage section

permission Object

• An object containing permission related constants for some security configurations
• For usage instruction, see Usage section

elysiaHelmet Function

• Creates an Elysia middleware that adds security headers to all responses
• Optimized for performance with minimal object spread operations
• For usage instruction, see Usage section

Use Case:

• Elysia.js

Requirements:

This library has peer dependency for Elysia.js 1.2.25. It may or may not work on 2.x

• 💀 Minimum elysia Version: 1.2.25

Usage:

To install the package, type the following in console

npm add @best-skn/elysia-helmet
#or
yarn add @best-skn/elysia-helmet
#or
pnpm add @best-skn/elysia-helmet
#or
bun add @best-skn/elysia-helmet

Basic Usage

import { Elysia } from "elysia";
import { elysiaHelmet } from "@best-skn/elysia-helmet";

const app = new Elysia()
  .use(elysiaHelmet({}))
  .get("/", () => "Hello, Secure World!")
  .listen(3000);

Note: Production mode is automatically enabled when NODE_ENV is set to 'production'. In production mode, additional security measures are enforced.

Advanced Configuration

import { Elysia } from "elysia";
import { elysiaHelmet, permission } from "@best-skn/elysia-helmet";

const app = new Elysia()
  .use(
    elysiaHelmet({
      csp: {
        defaultSrc: [permission.SELF],
        scriptSrc: [permission.SELF, permission.UNSAFE_INLINE],
        styleSrc: [permission.SELF, permission.UNSAFE_INLINE],
        imgSrc: [permission.SELF, permission.DATA, permission.HTTPS],
        useNonce: true,
      },
      hsts: {
        maxAge: 31536000,
        includeSubDomains: true,
        preload: true,
      },
      frameOptions: "DENY",
      referrerPolicy: "strict-origin-when-cross-origin",
      permissionsPolicy: {
        camera: [permission.NONE],
        microphone: [permission.NONE],
      },
    })
  )
  .listen(3000);

Types Usage

import type { CSPConfig, HSTSConfig, ReportToConfig, SecurityConfig } from "@best-skn/elysia-helmet";

These types are extremely useful if you want to define configurations in separate files

See Configuration Options below to get the type info

Configuration Options

Content Security Policy (CSP)

export interface CSPConfig {
  /** Default source directive */
  defaultSrc?: string[];
  /** Script source directive */
  scriptSrc?: string[];
  /** Style source directive */
  styleSrc?: string[];
  /** Image source directive */
  imgSrc?: string[];
  /** Font source directive */
  fontSrc?: string[];
  /** Connect source directive */
  connectSrc?: string[];
  /** Frame source directive */
  frameSrc?: string[];
  /** Object source directive */
  objectSrc?: string[];
  /** Base URI directive */
  baseUri?: string[];
  /** Report URI directive */
  reportUri?: string;
  /** Use nonce for script and style tags */
  useNonce?: boolean;
  /** Report-only mode */
  reportOnly?: boolean;
}

HSTS Configuration

export interface HSTSConfig {
  /** Maximum age */
  maxAge?: number;
  /** Include sub-domains */
  includeSubDomains?: boolean;
  /** Preload */
  preload?: boolean;
}

Report-To Configuration

export interface ReportToConfig {
  /** Group name for the endpoint */
  group: string;
  /** Maximum age of the endpoint configuration (in seconds) */
  maxAge: number;
  /** Endpoints to send reports to */
  endpoints: Array<{
    url: string;
    priority?: number;
    weight?: number;
  }>;
  /** Include subdomains in reporting */
  includeSubdomains?: boolean;
}

Security Configuration

export interface SecurityConfig {
  /** Content Security Policy configuration */
  csp?: CSPConfig;
  /** Enable or disable X-Frame-Options (DENY, SAMEORIGIN, ALLOW-FROM) */
  frameOptions?: "DENY" | "SAMEORIGIN" | "ALLOW-FROM";
  /** Enable or disable XSS Protection */
  xssProtection?: boolean;
  /** Enable or disable DNS Prefetch Control */
  dnsPrefetch?: boolean;
  /** Configure Referrer Policy */
  referrerPolicy?:
    | "no-referrer"
    | "no-referrer-when-downgrade"
    | "origin"
    | "origin-when-cross-origin"
    | "same-origin"
    | "strict-origin"
    | "strict-origin-when-cross-origin"
    | "unsafe-url";
  /** Configure Permissions Policy */
  permissionsPolicy?: Record<string, string[]>;
  /** Configure HSTS (HTTP Strict Transport Security) */
  hsts?: HSTSConfig;
  /** Enable or disable Cross-Origin Resource Policy */
  corp?: "same-origin" | "same-site" | "cross-origin";
  /** Enable or disable Cross-Origin Opener Policy */
  coop?: "unsafe-none" | "same-origin-allow-popups" | "same-origin";
  /** Configure Report-To header */
  reportTo?: ReportToConfig[];
  /** Custom headers to add */
  customHeaders?: Record<string, string>;
}

Permission Configuration

export const permission = {
  /** Source: Self allowed */
  SELF: "'self'",
  /** Source: Unsafe Inline allowed */
  UNSAFE_INLINE: "'unsafe-inline'",
  /** Source: HTTPS allowed */
  HTTPS: "https:",
  /** Source: Data allowed */
  DATA: "data:",
  /** Source: None is allowed */
  NONE: "'none'",
  /** Source: Blob allowed */
  BLOB: "blob:",
} as const;

Default Configuration

The middleware comes with secure defaults:

• CSP with 'self' as default source
• Frame options set to DENY
• XSS Protection enabled
• DNS Prefetch Control disabled
• Strict Referrer Policy
• And more secure defaults

You can override any of these defaults by passing your own configuration.

Dedicated To:

• 👩‍⚕️Tanjila Hasan Trina: The long lost love of my life. The course of nature separated us from our paths and put us in separate places far away from each other. But no matter how separated we are right now, each and every moment of mine is only dedicated to you. We may not see each other in this lifetime as it seems but I will find you again in the next life. I just want to say: 世界は残酷だ それでも君を愛すよ
• 💯My Parents: The greatest treasures of my life ever.

License:

Copyright (C) 2024 SKN Shukhan

Licensed under the MIT License

Credits:

• All credits for building the logic goes to aashahin