Arcjet Nosecone reference

Arcjet Nosecone is an open source library that helps set security headers such as Content-Security-Policy (CSP), Strict-Transport-Security (HSTS), and X-Content-Type-Options in JS applications built with Bun, Deno, Next.js, Node.js, or SvelteKit.

What are Arcjet utilities?

Arcjet utilities are independent libraries that do not require the use of the main Arcjet SDK—they can be used with or without other Arcjet rules.

We take the pain out of implementing security tasks through these utilities to provide a security as code approach to developer-first security.

Quick start

To get started, follow our quick start guide.

Next.js security headers middleware

Next.js security headers can be set using the @nosecone/next adapter.

This provides defaults to ensure Next.js applications work in production & development environments and the createMiddleware(options?: NoseconeOptions) API to create a Next.js middleware that runs on every request.

We recommend you remove any export const config = ... from your middleware so Nosecone will run on every route.

If the Content-Security-Policy header is specified via middleware, Next.js will look for a script-src that starts with nonce- and apply it for each <script> generated by the framework. This requires that opting-out of static generation, which requires modifying your Layout:

If you cannot opt-out of static generation, you will need to remove the nonce() function from the provided defaults.

Example configurations

Plausible Analytics + YouTube embed

This configuration applies the default Nosecone headers, but allows scripts from and connections to Plausible Analytics and YouTube embeds from the YouTube No Cookie domain (privacy enhanced mode).

It also sets the upgrade insecure requests directive to true in production to ensure all requests are served with HTTPS.

This configuration also enables the special handler for the Vercel Toolbar when deployed to Vercel preview environments.

1
import * as nosecone from "@nosecone/next";
2

3
const noseconeConfig: nosecone.NoseconeOptions = {
4
  ...nosecone.defaults,
5
  contentSecurityPolicy: {
6
    ...nosecone.defaults.contentSecurityPolicy,
7
    directives: {
8
      ...nosecone.defaults.contentSecurityPolicy.directives,
9
      scriptSrc: [
10
        ...nosecone.defaults.contentSecurityPolicy.directives.scriptSrc,
11
        "https://plausible.io", // Analytics
12
      ],
13
      connectSrc: [
14
        ...nosecone.defaults.contentSecurityPolicy.directives.connectSrc,
15
        "https://plausible.io", // Analytics
16
      ],
17
      // Set some URLs as `frameSrc` so don't include the default of `'none'`
18
      frameSrc: ["https://www.youtube-nocookie.com"],
19
      // We only set this in production because the server may be started
20
      // without HTTPS
21
      upgradeInsecureRequests: process.env.NODE_ENV === "production",
22
    },
23
  },
24
  crossOriginEmbedderPolicy: {
25
    // YouTube embeds are not served with the correct headers to support being
26
    // loaded with any COEP other than `unsafe-none`.
27
    // See:
28
    // * https://issuetracker.google.com/issues/240387105
29
    // * https://issuetracker.google.com/issues/351843802
30
    policy: "unsafe-none",
31
  },
32
} as const;
33

34
const noseconeMiddleware = nosecone.createMiddleware(
35
  process.env.VERCEL_ENV === "preview"
36
    ? nosecone.withVercelToolbar(noseconeConfig)
37
    : noseconeConfig,
38
);
39

40
export default noseconeMiddleware;

Clerk authentication

This configuration applies the default Nosecone headers, but allows scripts from and connections to Clerk for authentication.

1
import * as nosecone from "@nosecone/next";
2

3
const noseconeConfig: nosecone.NoseconeOptions = {
4
  ...nosecone.defaults,
5
  contentSecurityPolicy: {
6
    ...nosecone.defaults.contentSecurityPolicy,
7
    directives: {
8
      ...nosecone.defaults.contentSecurityPolicy.directives,
9
      scriptSrc: [
10
        ...nosecone.defaults.contentSecurityPolicy.directives.scriptSrc,
11
        "https://*.clerk.accounts.dev",
12
      ],
13
      connectSrc: [
14
        ...nosecone.defaults.contentSecurityPolicy.directives.connectSrc,
15
        "https://*.clerk.accounts.dev",
16
        "https://clerk-telemetry.com",
17
      ],
18
      workerSrc: [
19
        ...nosecone.defaults.contentSecurityPolicy.directives.workerSrc,
20
        "blob:",
21
        "https://*.clerk.accounts.dev",
22
      ],
23
      imgSrc: [
24
        ...nosecone.defaults.contentSecurityPolicy.directives.imgSrc,
25
        "https://img.clerk.com",
26
      ],
27
      objectSrc: [
28
        ...nosecone.defaults.contentSecurityPolicy.directives.objectSrc,
29
      ],
30
      // We only set this in production because the server may be started
31
      // without HTTPS
32
      upgradeInsecureRequests: process.env.NODE_ENV === "production",
33
    },
34
  },
35
} as const;
36

37
export default nosecone.createMiddleware(noseconeConfig);

Chaining middleware

If you are using multiple Next.js middleware functions, you can chain them together to add the security headers.

Auth.js example

This example shows how to chain Arcjet with Auth.js middleware:

Multiple middleware functions

If you have multiple middleware functions you will need to chain them together. We have written a small utility to help run different middleware for different paths.

In this example code, the Nosecone middleware is run on every route path. You can add other middleware into the array and add more paths to run different middleware.

Additional resources

SvelteKit security headers configuration

The @nosecone/sveltekit adapter provides defaults to ensure SvelteKit is configured correctly.

This also provides the csp(options?: ContentSecurityPolicyConfig) function to translate Nosecone configuration to SvelteKit configuration in svelte.config.js, and the createHook(options?: NoseconeOptions) function to create a SvelteKit hook that runs on every request.

Update your svelte.config.js to configure csp:

1
import adapter from "@sveltejs/adapter-auto";
2
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
3
import { csp } from "@nosecone/sveltekit"
4

5
/** @type {import('@sveltejs/kit').Config} */
6
const config = {
7
  preprocess: vitePreprocess(),
8

9
  kit: {
10
    // Apply CSP with Nosecone defaults
11
    csp: csp(),
12
    adapter: adapter(),
13
  },
14
};
15

16
export default config;

Additional resources:

API

`nosecone(options?: NoseconeOptions): Headers`

The default export is a function that returns a set of Headers to apply to a request that help you secure your application. The defaults should work for many applications, but all can be configured or disabled for specific requirements.

`NoseconeOptions`

All entries in NoseconeOptions can be enabled with defaults by specifying true or disabled by specifying false. Additionally, many allow individual configuration via their own configuration objects, which override any defaults.

You can use object spread, e.g. ...defaults, to combine the default values with your overrides.

1
interface NoseconeOptions {
2
  /**
3
   * Configure the `Content-Security-Policy` header, which helps mitigate a
4
   * large number of attacks, such as cross-site scripting.
5
   */
6
  contentSecurityPolicy?: ContentSecurityPolicyConfig | boolean;
7
  /**
8
   * Configure the `Cross-Origin-Embedder-Policy` header, which helps control
9
   * what resources can be loaded cross-origin.
10
   */
11
  crossOriginEmbedderPolicy?: CrossOriginEmbedderPolicyConfig | boolean;
12
  /**
13
   * Configure the `Cross-Origin-Opener-Policy` header, which helps
14
   * process-isolate your page.
15
   */
16
  crossOriginOpenerPolicy?: CrossOriginOpenerPolicyConfig | boolean;
17
  /**
18
   * Configure the `Cross-Origin-Resource-Policy` header, which blocks others
19
   * from loading your resources cross-origin in some cases.
20
   */
21
  crossOriginResourcePolicy?: CrossOriginResourcePolicyConfig | boolean;
22
  /**
23
   * Configure the `Origin-Agent-Cluster` header, which provides a mechanism to
24
   * allow web applications to isolate their origins from other processes.
25
   */
26
  originAgentCluster?: boolean;
27
  /**
28
   * Configure the `Referrer-Policy` header, which controls what information is
29
   * set in the `Referer` request header.
30
   */
31
  referrerPolicy?: ReferrerPolicyConfig | boolean;
32
  /**
33
   * Configure the `Strict-Transport-Security` header, which tells browsers to
34
   * prefer HTTPS instead of insecure HTTP.
35
   */
36
  strictTransportSecurity?: StrictTransportSecurityConfig | boolean;
37
  /**
38
   * Configure the `X-Content-Type-Options` header, which helps mitigate MIME
39
   * type sniffing that can cause security issues.
40
   */
41
  xContentTypeOptions?: boolean;
42
  /**
43
   * Configure the `X-DNS-Prefetch-Control` header, which helps control DNS
44
   * prefetching to improve user privacy at the expense of performance.
45
   */
46
  xDnsPrefetchControl?: DnsPrefetchControlConfig | boolean;
47
  /**
48
   * Configure the `X-Download-Options` header, which prevents a user from
49
   * opening a file directly in Internet Explorer 8 to avoid prevent script
50
   * injection.
51
   */
52
  xDownloadOptions?: boolean;
53
  /**
54
   * Configure the `X-Frame-Options` header, which helps mitigate clickjacking
55
   * attacks in legacy browsers. This header is superceded by a directive in the
56
   * `Content-Security-Policy` header.
57
   */
58
  xFrameOptions?: FrameOptionsConfig | boolean;
59
  /**
60
   * Configure the `X-Permitted-Cross-Domain-Policies` header, which tells some
61
   * clients, like Adobe products, your domain's policy for loading cross-domain
62
   * content.
63
   */
64
  xPermittedCrossDomainPolicies?: PermittedCrossDomainPoliciesConfig | boolean;
65
  /**
66
   * Disable the `X-XSS-Protection` header, which could introduce a browser
67
   * side-channel if enabled.
68
   */
69
  xXssProtection?: boolean;
70
}

`withVercelToolbar(options: NoseconeOptions): NoseconeOptions`

Nosecone provides the withVercelToolbar utility function to augment Nosecone options so the Vercel Toolbar is allowed by the various headers.

This follows the guidelines documented by Vercel under Using a Content Security Policy, but we recommend conditionally adding this based on process.env.VERCEL_ENV:

Headers

`Content-Security-Policy`

The Content-Security-Policy header is a powerful allow-list of what can happen on your page which helps mitigate many attacks, such as cross-site scripting.

Types:

1
type StaticOrDynamic<S> = boolean | readonly (S | (() => S))[] | null;

1
type Source =
2
  | `${string}.${string}`
3
  | "localhost"
4
  | `${string}.${string}:${number}`
5
  | `${string}.${string}:*`
6
  | `localhost:${number}`
7
  | "localhost:*"
8
  | `${string}://${string}.${string}`
9
  | `${string}://${string}.${string}:${number}`
10
  | `${string}://${string}.${string}:*`
11
  | `${string}://localhost`
12
  | `${string}://localhost:${number}`
13
  | `${string}://localhost:*`
14
  | "http:"
15
  | "https:"
16
  | "data:"
17
  | "mediastream:"
18
  | "blob:"
19
  | "filesystem:"
20
  | `'nonce-${string}'`
21
  | `'sha256-${string}'`
22
  | `'sha384-${string}'`
23
  | `'sha512-${string}'`
24
  | "'self'"
25
  | "'unsafe-eval'"
26
  | "'unsafe-hashes'"
27
  | "'unsafe-inline'"
28
  | "'wasm-unsafe-eval'"
29
  | "'none'";

1
type HostSource =
2
  | `${string}.${string}`
3
  | "localhost"
4
  | `${string}.${string}:${number}`
5
  | `${string}.${string}:*`
6
  | `localhost:${number}`
7
  | "localhost:*"
8
  | `${string}://${string}.${string}`
9
  | `${string}://${string}.${string}:${number}`
10
  | `${string}://${string}.${string}:*`
11
  | `${string}://localhost`
12
  | `${string}://localhost:${number}`
13
  | `${string}://localhost:*`;

1
type SchemeSource =
2
  | "http:"
3
  | "https:"
4
  | "data:"
5
  | "mediastream:"
6
  | "blob:"
7
  | "filesystem:";

1
type FrameSource =
2
  | `${string}.${string}`
3
  | "localhost"
4
  | `${string}.${string}:${number}`
5
  | `${string}.${string}:*`
6
  | `localhost:${number}`
7
  | "localhost:*"
8
  | `${string}://${string}.${string}`
9
  | `${string}://${string}.${string}:${number}`
10
  | `${string}://${string}.${string}:*`
11
  | `${string}://localhost`
12
  | `${string}://localhost:${number}`
13
  | `${string}://localhost:*`
14
  | "http:"
15
  | "https:"
16
  | "data:"
17
  | "mediastream:"
18
  | "blob:"
19
  | "filesystem:"
20
  | "'self'"
21
  | "'none'";

1
type ActionSource = "'strict-dynamic'" | "'report-sample'";

1
type CspDirectives = {
2
  baseUri?: StaticOrDynamic<Source | ActionSource> | undefined;
3
  childSrc?: StaticOrDynamic<Source> | undefined;
4
  defaultSrc?: StaticOrDynamic<Source | ActionSource> | undefined;
5
  frameSrc?: StaticOrDynamic<Source> | undefined;
6
  workerSrc?: StaticOrDynamic<Source> | undefined;
7
  connectSrc?: StaticOrDynamic<Source> | undefined;
8
  fontSrc?: StaticOrDynamic<Source> | undefined;
9
  imgSrc?: StaticOrDynamic<Source> | undefined;
10
  manifestSrc?: StaticOrDynamic<Source> | undefined;
11
  mediaSrc?: StaticOrDynamic<Source> | undefined;
12
  objectSrc?: StaticOrDynamic<Source> | undefined;
13
  prefetchSrc?: StaticOrDynamic<Source> | undefined;
14
  scriptSrc?: StaticOrDynamic<Source | ActionSource> | undefined;
15
  scriptSrcElem?: StaticOrDynamic<Source> | undefined;
16
  scriptSrcAttr?: StaticOrDynamic<Source> | undefined;
17
  styleSrc?: StaticOrDynamic<Source | ActionSource> | undefined;
18
  styleSrcElem?: StaticOrDynamic<Source> | undefined;
19
  styleSrcAttr?: StaticOrDynamic<Source> | undefined;
20
  sandbox?:
21
    | readonly (
22
        | "allow-downloads-without-user-activation"
23
        | "allow-forms"
24
        | "allow-modals"
25
        | "allow-orientation-lock"
26
        | "allow-pointer-lock"
27
        | "allow-popups"
28
        | "allow-popups-to-escape-sandbox"
29
        | "allow-presentation"
30
        | "allow-same-origin"
31
        | "allow-scripts"
32
        | "allow-storage-access-by-user-activation"
33
        | "allow-top-navigation"
34
        | "allow-top-navigation-by-user-activation"
35
      )[]
36
    | undefined;
37
  formAction?: StaticOrDynamic<Source | ActionSource> | undefined;
38
  frameAncestors?:
39
    | StaticOrDynamic<
40
        | `${string}.${string}`
41
        | "localhost"
42
        | `${string}.${string}:${number}`
43
        | `${string}.${string}:*`
44
        | `localhost:${number}`
45
        | "localhost:*"
46
        | `${string}://${string}.${string}`
47
        | `${string}://${string}.${string}:${number}`
48
        | `${string}://${string}.${string}:*`
49
        | `${string}://localhost`
50
        | `${string}://localhost:${number}`
51
        | `${string}://localhost:*`
52
        | "http:"
53
        | "https:"
54
        | "data:"
55
        | "mediastream:"
56
        | "blob:"
57
        | "filesystem:"
58
        | "'self'"
59
        | "'none'"
60
      >
61
    | undefined;
62
  navigateTo?: StaticOrDynamic<Source | ActionSource> | undefined;
63
  reportUri?: string[] | undefined | undefined;
64
  reportTo?: string[] | undefined | undefined;
65
  requireTrustedTypesFor?: readonly "script"[] | undefined;
66
  trustedTypes?: readonly string[] | undefined;
67
  upgradeInsecureRequests?: boolean | undefined | undefined;
68
};

1
type ContentSecurityPolicyConfig = {
2
  directives?: Readonly<CspDirectives> | undefined;
3
};

Defaults:

1
{
2
  directives: {
3
    baseUri: ["'none'"],
4
    childSrc: ["'none'"],
5
    connectSrc: ["'self'"],
6
    defaultSrc: ["'self'"],
7
    fontSrc: ["'self'"],
8
    formAction: ["'self'"],
9
    frameAncestors: ["'none'"],
10
    frameSrc: ["'none'"],
11
    imgSrc: ["'self'", "blob:", "data:"],
12
    manifestSrc: ["'self'"],
13
    mediaSrc: ["'self'"],
14
    objectSrc: ["'none'"],
15
    scriptSrc: ["'self'"],
16
    styleSrc: ["'self'"],
17
    workerSrc: ["'self'"],
18
  },
19
}

The defaults will produce the following header:

Content-Security-Policy: base-uri 'none'; child-src 'none'; connect-src 'self'; default-src 'self'; font-src 'self'; form-action 'self'; frame-ancestors 'none'; frame-src 'none'; img-src 'self' blob: data:; manifest-src 'self'; media-src 'self'; object-src 'none'; script-src 'self'; style-src 'self'; worker-src 'self';

Additional resources:

`Cross-Origin-Embedder-Policy`

The Cross-Origin-Embedder-Policy header helps control what resources can be loaded cross-origin.

Types:

1
type CrossOriginEmbedderPolicyConfig = {
2
  policy?:
3
    | "require-corp"
4
    | "credentialless"
5
    | "unsafe-none"
6
    | undefined
7
    | undefined;
8
};

Defaults:

1
{
2
  policy: "require-corp",
3
}

The defaults will produce the following header:

Cross-Origin-Embedder-Policy: require-corp

Additional resources:

`Cross-Origin-Opener-Policy`

The Cross-Origin-Opener-Policy header helps process-isolate your page.

Types:

1
type CrossOriginOpenerPolicyConfig = {
2
  policy?:
3
    | "same-origin"
4
    | "same-origin-allow-popups"
5
    | "unsafe-none"
6
    | undefined
7
    | undefined;
8
};

Defaults:

1
{
2
  policy: "same-origin",
3
}

The defaults will produce the following header:

Cross-Origin-Opener-Policy: same-origin

Additional resources:

`Cross-Origin-Resource-Policy`

The Cross-Origin-Resource-Policy header blocks others from loading your resources cross-origin in some cases.

Types:

1
type CrossOriginResourcePolicyConfig = {
2
  policy?: "same-origin" | "same-site" | "cross-origin" | undefined | undefined;
3
};

Defaults:

1
{
2
  policy: "same-origin",
3
}

The defaults will produce the following header:

Cross-Origin-Resource-Policy: same-origin

Additional resources:

`Origin-Agent-Cluster`

The Origin-Agent-Cluster header provides a mechanism to allow web applications to isolate their origins from other processes.

Types:

1
type OriginAgentClusterConfig = boolean;

Defaults:

1
true;

The defaults will produce the following header:

Origin-Agent-Cluster: ?1

Additional resources:

WHATPR Origin-keyed agent clusters specification

`Referrer-Policy`

The Referrer-Policy header controls what information is set in the Referer request header.

Types:

1
type ReferrerPolicyConfig = {
2
  policy?: readonly ReferrerPolicyToken[] | undefined;
3
};

1
type ReferrerPolicyToken =
2
  | ""
3
  | "no-referrer"
4
  | "no-referrer-when-downgrade"
5
  | "same-origin"
6
  | "origin"
7
  | "strict-origin"
8
  | "origin-when-cross-origin"
9
  | "strict-origin-when-cross-origin"
10
  | "unsafe-url";

Defaults:

1
{
2
  policy: ["no-referrer"],
3
}

The defaults will produce the following header:

Referrer-Policy: no-referrer

Additional resources:

`Strict-Transport-Security`

The Strict-Transport-Security header tells browsers to prefer HTTPS instead of insecure HTTP.

Types:

1
type StrictTransportSecurityConfig = {
2
  maxAge?: number | undefined | undefined;
3
  includeSubDomains?: boolean | undefined | undefined;
4
  preload?: boolean | undefined | undefined;
5
};

Defaults:

1
{
2
  maxAge: 31536000, // 1 year
3
  includeSubDomains: true,
4
  preload: false,
5
}

The defaults will produce the following header:

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

Additional resources:

`X-Content-Type-Options`

The X-Content-Type-Options header helps mitigate MIME type sniffing that can cause security issues.

Types:

1
type ContentTypeOptionsConfig = boolean;

Defaults:

1
true;

The defaults will produce the following header:

X-Content-Type-Options: nosniff

Additional resources:

`X-DNS-Prefetch-Control`

The X-DNS-Prefetch-Control header helps control DNS prefetching to improve user privacy at the expense of performance.

Types:

1
type DnsPrefetchControlConfig = {
2
  allow?: boolean | undefined | undefined;
3
};

Defaults:

1
{
2
  allow: false,
3
}

The defaults will produce the following header:

X-DNS-Prefetch-Control: off

Additional resources:

MDN’s X-DNS-Prefetch-Control reference

`X-Download-Options` (legacy)

The legacy X-Download-Options header prevented a user from opening a file directly in Internet Explorer to avoid prevent script injection.

Types:

1
type DownloadOptionsCofig = boolean;

Defaults:

1
true;

The defaults will produce the following header:

X-Download-Options: noopen

Additional resources:

Microsoft’s guide to securing IE8

`X-Frame-Options` (legacy)

The legacy X-Frame-Options header helped mitigate clickjacking attacks in older browsers.

Types:

1
type FrameOptionsConfig = {
2
  action?: "deny" | "sameorigin" | undefined | undefined;
3
};

Defaults:

1
{
2
  action: "sameorigin",
3
}

The defaults will produce the following header:

X-Frame-Options: SAMEORIGIN

Additional resources:

`X-Permitted-Cross-Domain-Policies`

The X-Permitted-Cross-Domain-Policies header tells some clients, like Adobe products, your domain’s policy for loading cross-domain content.

Types:

1
type PermittedCrossDomainPoliciesConfig = {
2
  permittedPolicies?:
3
    | "none"
4
    | "master-only"
5
    | "by-content-type"
6
    | "all"
7
    | undefined
8
    | undefined;
9
};

Defaults:

1
{
2
  permittedPolicies: "none",
3
}

The defaults will produce the following header:

X-Permitted-Cross-Domain-Policies: none

Additional resources:

OWASP Secure Headers Project - X-Permitted-Cross-Domain-Policies

`X-XSS-Protection` (legacy)

The legacy X-XSS-Protection header tried to mitigate XSS attacks, but accidentally enabled side-channel attacks in older browsers, so Nosecone disables it.

Types:

1
type XssProtectionConfig = boolean;

Defaults:

1
true;

The defaults will produce the following header:

X-XSS-Protection: 0

Additional resources:

Arcjet Nosecone reference

Quick start

Next.js security headers middleware

Example configurations

Plausible Analytics + YouTube embed

Clerk authentication

Chaining middleware

Auth.js example

Multiple middleware functions

Additional resources

SvelteKit security headers configuration

API

nosecone(options?: NoseconeOptions): Headers

NoseconeOptions

withVercelToolbar(options: NoseconeOptions): NoseconeOptions

Headers

Content-Security-Policy

Cross-Origin-Embedder-Policy

Cross-Origin-Opener-Policy

Cross-Origin-Resource-Policy

Origin-Agent-Cluster

Referrer-Policy

Strict-Transport-Security

X-Content-Type-Options

X-DNS-Prefetch-Control

X-Download-Options (legacy)

X-Frame-Options (legacy)

X-Permitted-Cross-Domain-Policies

X-XSS-Protection (legacy)

`nosecone(options?: NoseconeOptions): Headers`

`NoseconeOptions`

`withVercelToolbar(options: NoseconeOptions): NoseconeOptions`

`Content-Security-Policy`

`Cross-Origin-Embedder-Policy`

`Cross-Origin-Opener-Policy`

`Cross-Origin-Resource-Policy`

`Origin-Agent-Cluster`

`Referrer-Policy`

`Strict-Transport-Security`

`X-Content-Type-Options`

`X-DNS-Prefetch-Control`

`X-Download-Options` (legacy)

`X-Frame-Options` (legacy)

`X-Permitted-Cross-Domain-Policies`

`X-XSS-Protection` (legacy)