Skip to content

httpland/hsts-middleware

Repository files navigation

hsts-middleware

deno land deno doc GitHub release (latest by date) codecov GitHub

test NPM

HTTP Strict Transport Security(HSTS) middleware.

Compliant with RFC 6797, HTTP Strict Transport Security(HSTS).

Middleware

For a definition of Universal HTTP middleware, see the http-middleware project.

Usage

Middleware adds the Strict-Transport-Security header to the response.

import { hsts } from "https://deno.land/x/hsts_middleware@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
const middleware = hsts();
const response = await middleware(
  request,
  (request: Request) => new Response(),
);

assertEquals(
  response.headers.get(
    "strict-transport-security",
  ),
  "max-age=15552000; includeSubDomains",
);

Default is to add the following header to the response.

Strict-Transport-Security: max-age=15552000; includeSubDomains

Strict Transport Security

StrictTransportSecurity is a structured object of the Strict-Transport-Security Header.

Name Type Required Description
maxAge number The number of seconds, after the reception of the STS header field, during which the UA regards the host.
includeSubDomains boolean - Whether the rule applies to all subdomains or not.
preload boolean - Whether the domain do preload or not.

To enable HSTS preload, you will need to register HSTS look-ahead service.

import {
  hsts,
  type StrictTransportSecurity,
} from "https://deno.land/x/hsts_middleware@$VERSION/mod.ts";

const sts: StrictTransportSecurity = {
  maxAge: 60 * 60 * 24 * 365 * 2, // 2year,
  includeSubDomains: true,
  preload: true,
};
const middleware = hsts(sts);

yield:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

Throwing error

Strict Transport Security is an invalid value, it throws TypeError.

An invalid value is obtained in the following cases:

  • If maxAge is not a non-negative integer
import { hsts } from "https://deno.land/x/hsts_middleware@$VERSION/mod.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() => hsts({ maxAge: NaN }));

Preset

STS presets are provided. It is value recommended by several hosts.

import { hsts, STS } from "https://deno.land/x/hsts_middleware@$VERSION/mod.ts";

const middleware = hsts(STS);

yield:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

Effects

Middleware may make changes to the following elements of the HTTP message.

  • HTTP Headers
    • Strict-Transport-Security

Conditions

Middleware is executed if all of the following conditions are met

  • Strict-Transport-Security header does not exists in response

API

All APIs can be found in the deno doc.

License

Copyright © 2023-present httpland.

Released under the MIT license