JSPM

@best-skn/elysia-helmet

1.0.3
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q45078F
  • License MIT

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

Package Exports

  • @best-skn/elysia-helmet

Readme

SKN Elysia.js Helmet

Elysia Helmet

TypeScript

NPM Version MIT License

 

Introduction:

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

I created this library so that I can manage it all by myself and 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:

  • 👩‍🎨Prodipta Das Logno & 🧛‍♀️Atoshi Sarker Prithula: The two most special ladies of my life. My best wishes will always be with you two. May you two always be happy.
  • 💯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