nosecone
Version:
Protect your Response with secure headers
533 lines • 20.6 kB
TypeScript
//#region src/index.d.ts
type ActionSource = "'strict-dynamic'" | "'report-sample'";
type BaseSource = "'self'" | "'unsafe-eval'" | "'unsafe-hashes'" | "'unsafe-inline'" | "'wasm-unsafe-eval'" | "'none'";
type CryptoSource = `'${"nonce" | "sha256" | "sha384" | "sha512"}-${string}'`;
type FrameSource = HostSource | SchemeSource | "'self'" | "'none'";
type HostNameScheme = `${string}.${string}` | "localhost";
type HostSource = `${HostProtocolSchemes}${HostNameScheme}${PortScheme}`;
type HostProtocolSchemes = `${string}://` | "";
type PortScheme = `:${number}` | "" | ":*";
type SchemeSource = "http:" | "https:" | "data:" | "mediastream:" | "blob:" | "filesystem:";
type Source = HostSource | SchemeSource | CryptoSource | BaseSource;
type StaticOrDynamic<S> = boolean | null | ReadonlyArray<S | (() => S)>;
interface CspDirectives {
baseUri?: StaticOrDynamic<Source | ActionSource> | undefined;
childSrc?: StaticOrDynamic<Source> | undefined;
defaultSrc?: StaticOrDynamic<Source | ActionSource> | undefined;
frameSrc?: StaticOrDynamic<Source> | undefined;
workerSrc?: StaticOrDynamic<Source> | undefined;
connectSrc?: StaticOrDynamic<Source> | undefined;
fontSrc?: StaticOrDynamic<Source> | undefined;
imgSrc?: StaticOrDynamic<Source> | undefined;
manifestSrc?: StaticOrDynamic<Source> | undefined;
mediaSrc?: StaticOrDynamic<Source> | undefined;
objectSrc?: StaticOrDynamic<Source> | undefined;
prefetchSrc?: StaticOrDynamic<Source> | undefined;
scriptSrc?: StaticOrDynamic<Source | ActionSource> | undefined;
scriptSrcElem?: StaticOrDynamic<Source> | undefined;
scriptSrcAttr?: StaticOrDynamic<Source> | undefined;
styleSrc?: StaticOrDynamic<Source | ActionSource> | undefined;
styleSrcElem?: StaticOrDynamic<Source> | undefined;
styleSrcAttr?: StaticOrDynamic<Source> | undefined;
sandbox?: ReadonlyArray<"allow-downloads-without-user-activation" | "allow-forms" | "allow-modals" | "allow-orientation-lock" | "allow-pointer-lock" | "allow-popups" | "allow-popups-to-escape-sandbox" | "allow-presentation" | "allow-same-origin" | "allow-scripts" | "allow-storage-access-by-user-activation" | "allow-top-navigation" | "allow-top-navigation-by-user-activation"> | undefined;
formAction?: StaticOrDynamic<Source | ActionSource> | undefined;
frameAncestors?: StaticOrDynamic<HostSource | SchemeSource | FrameSource> | undefined;
navigateTo?: StaticOrDynamic<Source | ActionSource> | undefined;
reportUri?: string[] | undefined;
reportTo?: string[] | undefined;
requireTrustedTypesFor?: ReadonlyArray<"script"> | undefined;
trustedTypes?: ReadonlyArray<"none" | "allow-duplicates" | "*" | string> | undefined;
upgradeInsecureRequests?: boolean | undefined;
}
type ReferrerPolicyToken = "no-referrer" | "no-referrer-when-downgrade" | "same-origin" | "origin" | "strict-origin" | "origin-when-cross-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | "";
/**
* Configuration.
*/
interface ContentSecurityPolicyConfig {
/**
* Directives to use in the `Content-Security-Policy` header.
*/
directives?: Readonly<CspDirectives> | undefined;
}
/**
* Configuration for the `Cross-Origin-Embedder-Policy` header.
*/
interface CrossOriginEmbedderPolicyConfig {
/**
* Policy.
*/
policy?: "require-corp" | "credentialless" | "unsafe-none" | undefined;
}
/**
* Configuration for the `Cross-Origin-Opener-Policy` header.
*/
interface CrossOriginOpenerPolicyConfig {
/**
* Policy.
*/
policy?: "same-origin" | "same-origin-allow-popups" | "unsafe-none" | undefined;
}
/**
* Configuration for the `Cross-Origin-Resource-Policy` header.
*/
interface CrossOriginResourcePolicyConfig {
/**
* Policy.
*/
policy?: "same-origin" | "same-site" | "cross-origin" | undefined;
}
/**
* Configuration for the `Referrer-Policy` header.
*/
interface ReferrerPolicyConfig {
/**
* Policy.
*/
policy?: ReadonlyArray<ReferrerPolicyToken> | undefined;
}
/**
* Configuration for the `Strict-Transport-Security` header.
*/
interface StrictTransportSecurityConfig {
/**
* Max age in seconds.
*/
maxAge?: number | undefined;
/**
* Include subdomains.
*/
includeSubDomains?: boolean | undefined;
/**
* Preload.
*/
preload?: boolean | undefined;
}
/**
* Configuration for the `X-DNS-Prefetch-Control` header.
*/
interface DnsPrefetchControlConfig {
/**
* Allow DNS prefetching.
*/
allow?: boolean | undefined;
}
/**
* Configuration for the `X-Frame-Options` header.
*/
interface FrameOptionsConfig {
/**
* Action.
*/
action?: "deny" | "sameorigin" | undefined;
}
/**
* Configuration for the `X-Permitted-Cross-Domain-Policies` header.
*/
interface PermittedCrossDomainPoliciesConfig {
/**
* Permitted policies.
*/
permittedPolicies?: "none" | "master-only" | "by-content-type" | "all" | undefined;
}
/**
* Configuration.
*/
interface Options {
/**
* Configure the `Content-Security-Policy` header, which helps mitigate a
* large number of attacks, such as cross-site scripting.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link ContentSecurityPolicyConfig} to configure individual
* items.
*
* See also:
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
* - https://owasp.org/www-project-secure-headers/#content-security-policy
*/
contentSecurityPolicy?: ContentSecurityPolicyConfig | boolean | undefined;
/**
* Configure the `Cross-Origin-Embedder-Policy` header, which helps control
* what resources can be loaded cross-origin.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link CrossOriginEmbedderPolicyConfig} to configure individual
* items.
*
* See also:
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy
* - https://owasp.org/www-project-secure-headers/#cross-origin-embedder-policy
*/
crossOriginEmbedderPolicy?: CrossOriginEmbedderPolicyConfig | boolean | undefined;
/**
* Configure the `Cross-Origin-Opener-Policy` header, which helps
* process-isolate your page.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link CrossOriginOpenerPolicyConfig} to configure individual
* items.
*
* See also:
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy
* - https://owasp.org/www-project-secure-headers/#cross-origin-opener-policy
*/
crossOriginOpenerPolicy?: CrossOriginOpenerPolicyConfig | boolean | undefined;
/**
* Configure the `Cross-Origin-Resource-Policy` header, which blocks others
* from loading your resources cross-origin in some cases.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link CrossOriginResourcePolicyConfig} to configure individual
* items.
*
* See also:
* - https://resourcepolicy.fyi/
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy
* - https://owasp.org/www-project-secure-headers/#cross-origin-resource-policy
*/
crossOriginResourcePolicy?: CrossOriginResourcePolicyConfig | boolean | undefined;
/**
* Configure the `Origin-Agent-Cluster` header, which provides a mechanism to
* allow web applications to isolate their origins from other processes.
*
* Enable with defaults by specifying `true` or disable by specifying `false`.
*
* See also:
* - https://whatpr.org/html/6214/origin.html#origin-keyed-agent-clusters
*/
originAgentCluster?: boolean | undefined;
/**
* Configure the `Referrer-Policy` header, which controls what information is
* set in the `Referer` request header.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link ReferrerPolicyConfig} to configure individual items.
*
* See also:
* - https://developer.mozilla.org/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
* - https://owasp.org/www-project-secure-headers/#referrer-policy
*/
referrerPolicy?: ReferrerPolicyConfig | boolean | undefined;
/**
* Configure the `Strict-Transport-Security` header, which tells browsers to
* prefer HTTPS instead of insecure HTTP.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link StrictTransportSecurityConfig} to configure individual
* items.
*
* See also:
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
* - https://owasp.org/www-project-secure-headers/#strict-transport-security
*/
strictTransportSecurity?: StrictTransportSecurityConfig | boolean | undefined;
/**
* Configure the `X-Content-Type-Options` header, which helps mitigate MIME
* type sniffing that can cause security issues.
*
* Enable with defaults by specifying `true` or disable by specifying `false`.
*
* See also:
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/MIME_types#mime_sniffing
* - https://owasp.org/www-project-secure-headers/#x-content-type-options
*/
xContentTypeOptions?: boolean | undefined;
/**
* Configure the `X-DNS-Prefetch-Control` header, which helps control DNS
* prefetching to improve user privacy at the expense of performance.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link DnsPrefetchControlConfig} to configure individual items.
*
* See also:
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control
*/
xDnsPrefetchControl?: DnsPrefetchControlConfig | boolean | undefined;
/**
* Configure the `X-Download-Options` header, which prevents a user from
* opening a file directly in Internet Explorer 8 to avoid prevent script
* injection.
*
* Enable with defaults by specifying `true` or disable by specifying `false`.
*
* See also:
* - https://learn.microsoft.com/en-us/archive/blogs/ie/ie8-security-part-v-comprehensive-protection#mime-handling-force-save
*/
xDownloadOptions?: boolean | undefined;
/**
* Configure the `X-Frame-Options` header, which help mitigate clickjacking
* attacks in legacy browsers. This header is superceded by a directive in the
* `Content-Security-Policy` header.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link FrameOptionsConfig} to configure individual items.
*
* See also:
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
* - https://owasp.org/www-project-secure-headers/#x-frame-options
*/
xFrameOptions?: FrameOptionsConfig | boolean | undefined;
/**
* Configure the `X-Permitted-Cross-Domain-Policies` header, which tells some
* clients, like Adobe products, your domain's policy for loading cross-domain
* content.
*
* Enable with defaults by specifying `true`, disable by specifying `false`,
* or provide {@link PermittedCrossDomainPoliciesConfig} to configure
* individual items.
*
* See also:
* - https://owasp.org/www-project-secure-headers/#x-permitted-cross-domain-policies
*/
xPermittedCrossDomainPolicies?: PermittedCrossDomainPoliciesConfig | boolean | undefined;
/**
* Disable the `X-XSS-Protection` header, which could introduce a browser
* side-channel in legacy browsers if enabled.
*
* Disable it by specifying `true` or avoid setting the header by specifying
* `false`.
*
* See also:
* - https://github.com/helmetjs/helmet/issues/230
* - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection
* - https://owasp.org/www-project-secure-headers/#x-xss-protection
* - https://portswigger.net/daily-swig/new-xs-leak-techniques-reveal-fresh-ways-to-expose-user-information
*/
xXssProtection?: boolean | undefined;
}
/**
* Nosecone options.
*
* @deprecated
* Use `Options` instead.
*/
type NoseconeOptions = Options;
/**
* Map of configuration options to the kebab-case names for
* `Content-Security-Policy` directives.
*/
declare const CONTENT_SECURITY_POLICY_DIRECTIVES: Map<string, string>;
/**
* Set of valid `Cross-Origin-Embedder-Policy` values.
*/
declare const CROSS_ORIGIN_EMBEDDER_POLICIES: Set<"require-corp" | "credentialless" | "unsafe-none">;
/**
* Set of valid `Cross-Origin-Opener-Policy` values.
*/
declare const CROSS_ORIGIN_OPENER_POLICIES: Set<"same-origin" | "same-origin-allow-popups" | "unsafe-none">;
/**
* Set of valid `Cross-Origin-Resource-Policy` values.
*/
declare const CROSS_ORIGIN_RESOURCE_POLICIES: Set<"same-origin" | "same-site" | "cross-origin">;
/**
* Set of valid `Resource-Policy` tokens.
*/
declare const REFERRER_POLICIES: Set<"no-referrer" | "no-referrer-when-downgrade" | "same-origin" | "origin" | "strict-origin" | "origin-when-cross-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | "">;
/**
* Set of valid `X-Permitted-Cross-Domain-Policies` values.
*/
declare const PERMITTED_CROSS_DOMAIN_POLICIES: Set<"none" | "master-only" | "by-content-type" | "all">;
/**
* Set of valid values for the `sandbox` directive of `Content-Security-Policy`.
*/
declare const SANDBOX_DIRECTIVES: Set<"allow-downloads-without-user-activation" | "allow-forms" | "allow-modals" | "allow-orientation-lock" | "allow-pointer-lock" | "allow-popups" | "allow-popups-to-escape-sandbox" | "allow-presentation" | "allow-same-origin" | "allow-scripts" | "allow-storage-access-by-user-activation" | "allow-top-navigation" | "allow-top-navigation-by-user-activation">;
/**
* Mapping of values that need to be quoted in `Content-Security-Policy`;
* however, it does not include `nonce-*` or `sha*-*` because those are dynamic.
*/
declare const QUOTED: Map<string, string>;
/**
* Default configuration for headers.
*/
declare const defaults: {
readonly contentSecurityPolicy: {
readonly directives: {
readonly baseUri: readonly ["'none'"];
readonly childSrc: readonly ["'none'"];
readonly connectSrc: readonly ["'self'"];
readonly defaultSrc: readonly ["'self'"];
readonly fontSrc: readonly ["'self'"];
readonly formAction: readonly ["'self'"];
readonly frameAncestors: readonly ["'none'"];
readonly frameSrc: readonly ["'none'"];
readonly imgSrc: readonly ["'self'", "blob:", "data:"];
readonly manifestSrc: readonly ["'self'"];
readonly mediaSrc: readonly ["'self'"];
readonly objectSrc: readonly ["'none'"];
readonly scriptSrc: readonly ["'self'"];
readonly styleSrc: readonly ["'self'"];
readonly workerSrc: readonly ["'self'"];
};
};
readonly crossOriginEmbedderPolicy: {
readonly policy: "require-corp";
};
readonly crossOriginOpenerPolicy: {
readonly policy: "same-origin";
};
readonly crossOriginResourcePolicy: {
readonly policy: "same-origin";
};
readonly originAgentCluster: true;
readonly referrerPolicy: {
readonly policy: readonly ["no-referrer"];
};
readonly strictTransportSecurity: {
readonly maxAge: 31_536_000;
readonly includeSubDomains: true;
readonly preload: false;
};
readonly xContentTypeOptions: true;
readonly xDnsPrefetchControl: {
readonly allow: false;
};
readonly xDownloadOptions: true;
readonly xFrameOptions: {
readonly action: "sameorigin";
};
readonly xPermittedCrossDomainPolicies: {
readonly permittedPolicies: "none";
};
readonly xXssProtection: true;
};
/**
* Kind of error thrown when configuration is invalid.
*/
declare class NoseconeValidationError extends Error {
/**
* Create a new `NoseconeValidationError`.
*
* @param message
* Error message.
*/
constructor(message: string);
}
/**
* Create a `Content-Security-Policy` header.
*
* @param options
* Configuration.
* @returns
* `Content-Security-Policy` header.
*/
declare function createContentSecurityPolicy(options?: ContentSecurityPolicyConfig | undefined): readonly [string, string];
/**
* Create a `Cross-Origin-Embedder-Policy` header.
*
* @param options
* Configuration.
* @returns
* `Cross-Origin-Embedder-Policy` header.
*/
declare function createCrossOriginEmbedderPolicy(options?: CrossOriginEmbedderPolicyConfig | undefined): readonly [string, string];
/**
* Create a `Cross-Origin-Opener-Policy` header.
*
* @param options
* Configuration.
* @returns
* `Cross-Origin-Opener-Policy` header.
*/
declare function createCrossOriginOpenerPolicy(options?: CrossOriginOpenerPolicyConfig | undefined): readonly [string, string];
/**
* Create a `Cross-Origin-Resource-Policy` header.
*
* @param options
* Configuration.
* @returns
* `Cross-Origin-Resource-Policy` header.
*/
declare function createCrossOriginResourcePolicy(options?: CrossOriginResourcePolicyConfig | undefined): readonly [string, string];
/**
* Create a `Origin-Agent-Cluster` header.
*
* @returns
* `Origin-Agent-Cluster` header.
*/
declare function createOriginAgentCluster(): readonly ["origin-agent-cluster", "?1"];
/**
* Create a `Referrer-Policy` header.
*
* @param options
* Configuration.
* @returns
* `Referrer-Policy` header.
*/
declare function createReferrerPolicy(options?: ReferrerPolicyConfig | undefined): readonly [string, string];
/**
* Create a `Strict-Transport-Security` header.
*
* @param options
* Configuration.
* @returns
* `Strict-Transport-Security` header.
*/
declare function createStrictTransportSecurity(options?: StrictTransportSecurityConfig | undefined): readonly [string, string];
/**
* Create an `X-Content-Type-Options` header.
*
* @returns
* `X-Content-Type-Options` header.
*/
declare function createContentTypeOptions(): readonly ["x-content-type-options", "nosniff"];
/**
* Create an `X-DNS-Prefetch-Control` header.
*
* @param options
* Configuration.
* @returns
* `X-DNS-Prefetch-Control` header.
*/
declare function createDnsPrefetchControl(options?: DnsPrefetchControlConfig | undefined): readonly [string, string];
declare function createDownloadOptions(): readonly ["x-download-options", "noopen"];
/**
* Create an `X-Frame-Options` header.
*
* @param options
* Configuration.
* @returns
* `X-Frame-Options` header.
*/
declare function createFrameOptions(options?: FrameOptionsConfig | undefined): readonly [string, string];
/**
* Create an `X-Permitted-Cross-Domain-Policies` header.
*
* @param options
* Configuration.
* @returns
* `X-Permitted-Cross-Domain-Policies` header.
*/
declare function createPermittedCrossDomainPolicies(options?: PermittedCrossDomainPoliciesConfig | undefined): readonly [string, string];
/**
* Create an `X-XSS-Protection` header.
*
* @returns
* `X-XSS-Protection` header.
*/
declare function createXssProtection(): readonly ["x-xss-protection", "0"];
/**
* Create security headers.
*
* @param options
* Configuration.
* @returns
* `Headers` with the configured security headers.
*/
declare function nosecone(options?: Options | undefined): Headers;
/**
* Augment some Nosecone configuration with the values necessary for using the
* Vercel Toolbar.
*
* Follows the guidance at [*Using a Content Security Policy* on
* `vercel.com`](https://vercel.com/docs/vercel-toolbar/managing-toolbar#using-a-content-security-policy).
*
* @param config
* Base configuration for your application
* @returns
* Augmented configuration to allow Vercel Toolbar
*/
declare function withVercelToolbar(config: Options): Options;
//#endregion
export { ActionSource, BaseSource, CONTENT_SECURITY_POLICY_DIRECTIVES, CROSS_ORIGIN_EMBEDDER_POLICIES, CROSS_ORIGIN_OPENER_POLICIES, CROSS_ORIGIN_RESOURCE_POLICIES, ContentSecurityPolicyConfig, CrossOriginEmbedderPolicyConfig, CrossOriginOpenerPolicyConfig, CrossOriginResourcePolicyConfig, CryptoSource, CspDirectives, DnsPrefetchControlConfig, FrameOptionsConfig, FrameSource, HostNameScheme, HostProtocolSchemes, HostSource, NoseconeOptions, NoseconeValidationError, Options, PERMITTED_CROSS_DOMAIN_POLICIES, PermittedCrossDomainPoliciesConfig, PortScheme, QUOTED, REFERRER_POLICIES, ReferrerPolicyConfig, ReferrerPolicyToken, SANDBOX_DIRECTIVES, SchemeSource, Source, StaticOrDynamic, StrictTransportSecurityConfig, createContentSecurityPolicy, createContentTypeOptions, createCrossOriginEmbedderPolicy, createCrossOriginOpenerPolicy, createCrossOriginResourcePolicy, createDnsPrefetchControl, createDownloadOptions, createFrameOptions, createOriginAgentCluster, createPermittedCrossDomainPolicies, createReferrerPolicy, createStrictTransportSecurity, createXssProtection, nosecone as default, nosecone, defaults, withVercelToolbar };