granular interface

Author: nichtsam

README.md

@@ -1,21 +1,15 @@
 # Helmet Security Headers Library
 
-Helps to secure apps by setting HTTP response headers.
-Inspired by [`helmet`](https://github.com/helmetjs/helmet) and [`http-helmet`](https://github.com/mcansh/http-helmet)
+Helps secure applications by setting HTTP response headers.
+Inspired by [`helmet`](https://github.com/helmetjs/helmet) and [`http-helmet`](https://github.com/mcansh/http-helmet).
 
 ## Overview
 
-This package provides a flexible and modular way for managing security headers in a structured way.
+This package provides a flexible and modular way for managing security headers in a structured manner.
 
-- **General security headers**
-- **HTML-specific headers** (e.g., `Content-Security-Policy`, `X-Download-Options`)
-- **CORS-related configurations**
-
-## Features
-
-- Returns security headers with sensible defaults (inspired by Express Helmet)
-- **HTML-specific options** are only applied when `html: true` is set
-- **Cross-Origin-Resource-Policy** defaults to `'same-origin'`, but switches to `'cross-origin'` if `cors: true`
+- Provides security headers with sensible defaults (inspired by Express Helmet).
+- Content-specific options available as needed.
+- Resource Sharing Security Headers.
 
 ## Installation
 
@@ -25,22 +19,70 @@ npm install @nichtsam/helmet
 
 ## Usage
 
-```ts
-import helmet from "@nichtsam/helmet";
+This is the most basic usage, which applies security headers for general purpose, best practices for protecting any type of resource.
 
+```ts
+import { helmet } from "@nichtsam/helmet";
 const headers = new Headers();
-
-// general
 helmet(headers);
-// with html
-helmet(headers, { html: true });
-// non html with cors
-helmet(headers, { cors: true });
-// customize rules
+```
+
+There are options to enable more detailed security headers, such as for html webpage contents.
+
+```ts
 helmet(headers, {
-  options: {
-    crossOriginEmbedderPolicy: false,
-    contentSecurityPolicy: {},
-  },
+  content: { contentSecurityPolicy: {} },
+});
+```
+
+If you want to share the resource across origins, you can enable the resourceSharing option.
+
+```ts
+helmet(headers, { resourceSharing: true });
+```
+
+> [!IMPORTANT]  
+> This only sets the headers for enhanced security.
+> You are responsible for setting the correct CORS headers.
+> https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#the_http_request_headers
+
+### For `node-http`
+
+The package provides a simple wrapper to make it smoother to use on `http.ServerResponse`.
+For example in an express app:
+
+```ts
+import { helmet } from "@nichtsam/helmet/node-http";
+
+const app = express();
+app.use((req, res, next) => {
+  helmet(res);
+  next();
 });
 ```
+
+### Granular Interface
+
+The main `helmet` function integrates all the security rules, you can find them all individually under `@nichtsam/helmet/rules`.
+They're categorized under `general`, `content` and `resourceSharing`, just like the options in the integrated `helmet` function.
+This allows for a layered application approach to better suit individual routes.
+
+For example:
+
+```ts
+import { generalSecurity } from "@nichtsam/helmet/rules/general/index";
+import { contentSecurity } from "@nichtsam/helmet/rules/content/index";
+import { resourceSharingSecurity } from "@nichtsam/helmet/rules/resourceSharing/index";
+
+const headers = new Headers();
+// on root level
+generalSecurity(headers);
+// after the content-type is set
+contentSecurity(headers);
+// if you want to share across origins
+resourceSharingSecurity(headers, { strategy: "cross-origin" });
+```
+
+> [!NOTE]  
+> The `generalSecurity` function includes `resourceSharingSecurity(headers, { strategy: "same-origin" })` by default.
+> So you only need to call `resourceSharingSecurity` if you want to share resources across origins or customize the strategy.

package.json

@@ -4,11 +4,7 @@
   "name": "@nichtsam/helmet",
   "version": "0.1.0",
   "license": "MIT",
-  "keywords": [
-    "web",
-    "security",
-    "helmet"
-  ],
+  "keywords": ["web", "security", "helmet"],
   "author": {
     "name": "Samuel Jensen",
     "url": "https://nichtsam.com"
@@ -27,14 +23,11 @@
     "quality": "biome check .",
     "quality:fix": "biome check . --write --unsafe"
   },
-  "files": [
-    "build",
-    "package.json",
-    "README.md"
-  ],
+  "files": ["build", "package.json", "README.md"],
   "exports": {
     ".": "./build/index.js",
-    "./*": "./build/rules/*.js",
+    "./node-http": "./build/node-http.js",
+    "./rules/*": "./build/rules/*.js",
     "./package.json": "./package.json"
   },
   "devDependencies": {

src/index.ts

@@ -1,194 +1,76 @@
 import {
-  type ContentSecurityPolicyOptions,
-  type CrossOriginEmbedderPolicyOptions,
-  type CrossOriginOpenerPolicyOptions,
-  type CrossOriginResourcePolicyOptions,
-  type ReferrerPolicyOptions,
-  type StrictTransportSecurityOptions,
-  type XDnsPrefetchControlOptions,
-  type XFrameOptionsOptions,
-  type XPermittedCrossDomainPoliciesOptions,
-  contentSecurityPolicy,
-  crossOriginEmbedderPolicy,
-  crossOriginOpenerPolicy,
-  crossOriginResourcePolicy,
-  originAgentCluster,
-  referrerPolicy,
-  strictTransportSecurity,
-  xContentTypeOptions,
-  xDnsPrefetchControl,
-  xDownloadOptions,
-  xFrameOptions,
-  xPermittedCrossDomainPolicies,
-  xXssProtection,
-} from "./rules/index.js";
+  type ContentSecureOptions,
+  contentSecurity,
+} from "./rules/content/index.js";
+import {
+  type GeneralSecureOptions,
+  generalSecurity,
+} from "./rules/general/index.js";
+import {
+  type ResourceSharingSecureOptions,
+  resourceSharing,
+} from "./rules/resourceSharing/index.js";
+
+const headers = new Headers();
+helmet(headers, { content: { contentSecurityPolicy: {} } });
+
+helmet(headers, { resourceSharing: true });
 
 /**
- * Sets sensible security headers onto a Headers instance.
- *
- * This utility function configures security headers based on the provided settings.
+ * Applies security headers to a `Headers` instance with sensible defaults.
+ * General security headers are always set, while content and resource-sharing headers can be opted in.
  */
-export function helmet(
-  headers: Headers,
-  { options = {}, html = false, cors = false }: HelmetOptions = {},
-) {
-  switch (options.crossOriginResourcePolicy) {
+export function helmet(headers: Headers, options: HelmetOptions = {}) {
+  switch (options.general) {
     case undefined:
     case true:
-      crossOriginResourcePolicy(headers, cors ? "cross-origin" : "same-origin");
+      generalSecurity(headers);
       break;
     case false:
       break;
     default:
-      crossOriginResourcePolicy(headers, options.crossOriginResourcePolicy);
-  }
-
-  if (options.originAgentCluster ?? true) {
-    originAgentCluster(headers);
+      generalSecurity(headers, options.general);
   }
 
-  switch (options.referrerPolicy) {
+  switch (options.content) {
     case undefined:
-    case true:
-      referrerPolicy(headers);
-      break;
     case false:
       break;
-    default:
-      referrerPolicy(headers, options.referrerPolicy);
-  }
-
-  switch (options.strictTransportSecurity) {
-    case undefined:
     case true:
-      strictTransportSecurity(headers);
-      break;
-    case false:
+      contentSecurity(headers);
       break;
     default:
-      strictTransportSecurity(headers, options.strictTransportSecurity);
+      contentSecurity(headers, options.content);
   }
 
-  if (options.xContentTypeOptions ?? true) {
-    xContentTypeOptions(headers);
-  }
-
-  switch (options.xDnsPrefetchControl) {
+  switch (options.resourceSharing) {
     case undefined:
-    case true:
-      xDnsPrefetchControl(headers);
-      break;
     case false:
       break;
-    default:
-      xDnsPrefetchControl(headers, options.xDnsPrefetchControl);
-  }
-
-  switch (options.xPermittedCrossDomainPolicies) {
-    case undefined:
     case true:
-      xPermittedCrossDomainPolicies(headers);
-      break;
-    case false:
+      resourceSharing(headers);
       break;
     default:
-      xPermittedCrossDomainPolicies(
-        headers,
-        options.xPermittedCrossDomainPolicies,
-      );
-  }
-
-  if (options.xXssProtection ?? true) {
-    xXssProtection(headers);
-  }
-
-  if (html) {
-    switch (options.contentSecurityPolicy) {
-      case undefined:
-      case true:
-        contentSecurityPolicy(headers);
-        break;
-      case false:
-        break;
-      default:
-        contentSecurityPolicy(headers, options.contentSecurityPolicy);
-    }
-
-    switch (options.crossOriginOpenerPolicy) {
-      case undefined:
-      case true:
-        crossOriginOpenerPolicy(headers);
-        break;
-      case false:
-        break;
-      default:
-        crossOriginOpenerPolicy(headers, options.crossOriginOpenerPolicy);
-    }
-
-    switch (options.crossOriginEmbedderPolicy) {
-      case undefined:
-      case true:
-        crossOriginEmbedderPolicy(headers);
-        break;
-      case false:
-        break;
-      default:
-        crossOriginEmbedderPolicy(headers, options.crossOriginEmbedderPolicy);
-    }
-
-    if (options.xDownloadOptions ?? true) {
-      xDownloadOptions(headers);
-    }
-
-    switch (options.xFrameOptions) {
-      case undefined:
-      case true:
-        xFrameOptions(headers);
-        break;
-      case false:
-        break;
-      default:
-        xFrameOptions(headers, options.xFrameOptions);
-    }
+      resourceSharing(headers, options.resourceSharing);
   }
 }
 
 export type HelmetOptions = {
   /**
-   * Options to enable, disable defaults, or customized security headers for your own need
+   * Configures general security headers.
+   * Enabled by default.
    */
-  options?: SecureOptions;
+  general?: GeneralSecureOptions | boolean;
   /**
-   * Whether the content type is html, this enables document specific security headers.
-   * @default {true}
+   * Configures security headers relevant to content, typically for `text/html` responses.
+   * Disabled by default.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Glossary/Browsing_context
    */
-  html?: boolean;
+  content?: ContentSecureOptions | boolean;
   /**
-   * Whether the content is shared cross-origin, this modifys defaults to support cross origin resource sharing.
-   * @default {false}
+   * Configures security headers related to resource sharing (CORS).
+   * Disabled by default.
    */
-  cors?: boolean;
-};
-
-export type SecureOptions = GeneralSecureOptions & HtmlSpecificSecureOptions;
-
-type GeneralSecureOptions = {
-  crossOriginResourcePolicy?: CrossOriginResourcePolicyOptions | boolean;
-  originAgentCluster?: boolean;
-  referrerPolicy?: ReferrerPolicyOptions | boolean;
-  strictTransportSecurity?: StrictTransportSecurityOptions | boolean;
-  xContentTypeOptions?: boolean;
-  xDnsPrefetchControl?: XDnsPrefetchControlOptions | boolean;
-  xPermittedCrossDomainPolicies?:
-    | XPermittedCrossDomainPoliciesOptions
-    | boolean;
-  xXssProtection?: boolean;
-};
-
-type HtmlSpecificSecureOptions = {
-  contentSecurityPolicy?: ContentSecurityPolicyOptions | boolean;
-  crossOriginOpenerPolicy?: CrossOriginOpenerPolicyOptions | boolean;
-  crossOriginEmbedderPolicy?: CrossOriginEmbedderPolicyOptions | boolean;
-  xDownloadOptions?: boolean;
-  xFrameOptions?: XFrameOptionsOptions | boolean;
+  resourceSharing?: ResourceSharingSecureOptions | boolean;
 };

src/node-http.ts

@@ -0,0 +1,13 @@
+import type { ServerResponse } from "node:http";
+import { type HelmetOptions, helmet as _helmet } from "./index.js";
+
+/**
+ * Sets sensible security headers onto `http.ServerResponse`.
+ *
+ * This utility function configures security headers based on the provided settings.
+ */
+export function helmet(response: ServerResponse, options?: HelmetOptions) {
+  const headers = new Headers();
+  _helmet(headers, options);
+  response.setHeaders(headers);
+}

src/rules/content-security-policy.ts …rules/content/content-security-policy.tssrc/rules/content-security-policy.ts renamed to src/rules/content/content-security-policy.ts src/rules/content-security-policy.ts renamed to src/rules/content/content-security-policy.ts

@@ -1,4 +1,4 @@
-import type { SmartString } from "../helpers/types.js";
+import type { SmartString } from "../../helpers/types.js";
 
 /**
  * Sets `Content-Security-Policy` headers onto a `Headers` instance.