nosecone
Version:
Protect your Response with secure headers
337 lines (336 loc) • 18.9 kB
TypeScript
export type ActionSource = "'strict-dynamic'" | "'report-sample'";
export type BaseSource = "'self'" | "'unsafe-eval'" | "'unsafe-hashes'" | "'unsafe-inline'" | "'wasm-unsafe-eval'" | "'none'";
export type CryptoSource = `'${"nonce" | "sha256" | "sha384" | "sha512"}-${string}'`;
export type FrameSource = HostSource | SchemeSource | "'self'" | "'none'";
export type HostNameScheme = `${string}.${string}` | "localhost";
export type HostSource = `${HostProtocolSchemes}${HostNameScheme}${PortScheme}`;
export type HostProtocolSchemes = `${string}://` | "";
export type PortScheme = `:${number}` | "" | ":*";
export type SchemeSource = "http:" | "https:" | "data:" | "mediastream:" | "blob:" | "filesystem:";
export type Source = HostSource | SchemeSource | CryptoSource | BaseSource;
export type StaticOrDynamic<S> = boolean | null | ReadonlyArray<S | (() => S)>;
export interface CspDirectives {
baseUri?: StaticOrDynamic<Source | ActionSource>;
childSrc?: StaticOrDynamic<Source>;
defaultSrc?: StaticOrDynamic<Source | ActionSource>;
frameSrc?: StaticOrDynamic<Source>;
workerSrc?: StaticOrDynamic<Source>;
connectSrc?: StaticOrDynamic<Source>;
fontSrc?: StaticOrDynamic<Source>;
imgSrc?: StaticOrDynamic<Source>;
manifestSrc?: StaticOrDynamic<Source>;
mediaSrc?: StaticOrDynamic<Source>;
objectSrc?: StaticOrDynamic<Source>;
prefetchSrc?: StaticOrDynamic<Source>;
scriptSrc?: StaticOrDynamic<Source | ActionSource>;
scriptSrcElem?: StaticOrDynamic<Source>;
scriptSrcAttr?: StaticOrDynamic<Source>;
styleSrc?: StaticOrDynamic<Source | ActionSource>;
styleSrcElem?: StaticOrDynamic<Source>;
styleSrcAttr?: StaticOrDynamic<Source>;
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">;
formAction?: StaticOrDynamic<Source | ActionSource>;
frameAncestors?: StaticOrDynamic<HostSource | SchemeSource | FrameSource>;
navigateTo?: StaticOrDynamic<Source | ActionSource>;
reportUri?: string[];
reportTo?: string[];
requireTrustedTypesFor?: ReadonlyArray<"script">;
trustedTypes?: ReadonlyArray<"none" | "allow-duplicates" | "*" | string>;
upgradeInsecureRequests?: boolean;
}
export type ReferrerPolicyToken = "no-referrer" | "no-referrer-when-downgrade" | "same-origin" | "origin" | "strict-origin" | "origin-when-cross-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | "";
export interface ContentSecurityPolicyConfig {
directives?: Readonly<CspDirectives>;
}
export interface CrossOriginEmbedderPolicyConfig {
policy?: "require-corp" | "credentialless" | "unsafe-none";
}
export interface CrossOriginOpenerPolicyConfig {
policy?: "same-origin" | "same-origin-allow-popups" | "unsafe-none";
}
export interface CrossOriginResourcePolicyConfig {
policy?: "same-origin" | "same-site" | "cross-origin";
}
export interface ReferrerPolicyConfig {
policy?: ReadonlyArray<ReferrerPolicyToken>;
}
export interface StrictTransportSecurityConfig {
maxAge?: number;
includeSubDomains?: boolean;
preload?: boolean;
}
export interface DnsPrefetchControlConfig {
allow?: boolean;
}
export interface FrameOptionsConfig {
action?: "deny" | "sameorigin";
}
export interface PermittedCrossDomainPoliciesConfig {
permittedPolicies?: "none" | "master-only" | "by-content-type" | "all";
}
export interface NoseconeOptions {
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
/**
* 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;
}
export declare const CONTENT_SECURITY_POLICY_DIRECTIVES: Map<"baseUri" | "childSrc" | "defaultSrc" | "frameSrc" | "workerSrc" | "connectSrc" | "fontSrc" | "imgSrc" | "manifestSrc" | "mediaSrc" | "objectSrc" | "prefetchSrc" | "scriptSrc" | "scriptSrcElem" | "scriptSrcAttr" | "styleSrc" | "styleSrcElem" | "styleSrcAttr" | "sandbox" | "formAction" | "frameAncestors" | "navigateTo" | "reportUri" | "reportTo" | "requireTrustedTypesFor" | "trustedTypes" | "upgradeInsecureRequests", "base-uri" | "child-src" | "default-src" | "frame-src" | "worker-src" | "connect-src" | "font-src" | "img-src" | "manifest-src" | "media-src" | "object-src" | "prefetch-src" | "script-src" | "script-src-elem" | "script-src-attr" | "style-src" | "style-src-elem" | "style-src-attr" | "sandbox" | "form-action" | "frame-ancestors" | "navigate-to" | "report-uri" | "report-to" | "require-trusted-types-for" | "trusted-types" | "upgrade-insecure-requests">;
export declare const CROSS_ORIGIN_EMBEDDER_POLICIES: Set<"require-corp" | "credentialless" | "unsafe-none">;
export declare const CROSS_ORIGIN_OPENER_POLICIES: Set<"same-origin" | "unsafe-none" | "same-origin-allow-popups">;
export declare const CROSS_ORIGIN_RESOURCE_POLICIES: Set<"same-origin" | "same-site" | "cross-origin">;
export 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">;
export declare const PERMITTED_CROSS_DOMAIN_POLICIES: Set<"none" | "master-only" | "by-content-type" | "all">;
export 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">;
export declare const QUOTED: Map<"script" | "none" | "self" | "unsafe-eval" | "unsafe-hashes" | "unsafe-inline" | "strict-dynamic" | "report-sample" | "wasm-unsafe-eval", "'strict-dynamic'" | "'report-sample'" | "'self'" | "'unsafe-eval'" | "'unsafe-hashes'" | "'unsafe-inline'" | "'wasm-unsafe-eval'" | "'none'" | "'script'">;
export 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: number;
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;
};
export declare class NoseconeValidationError extends Error {
constructor(message: string);
}
export declare function createContentSecurityPolicy({ directives, }?: ContentSecurityPolicyConfig): readonly ["content-security-policy", string];
export declare function createCrossOriginEmbedderPolicy({ policy, }?: CrossOriginEmbedderPolicyConfig): readonly ["cross-origin-embedder-policy", "require-corp" | "credentialless" | "unsafe-none"];
export declare function createCrossOriginOpenerPolicy({ policy, }?: CrossOriginOpenerPolicyConfig): readonly ["cross-origin-opener-policy", "same-origin" | "unsafe-none" | "same-origin-allow-popups"];
export declare function createCrossOriginResourcePolicy({ policy, }?: CrossOriginResourcePolicyConfig): readonly ["cross-origin-resource-policy", "same-origin" | "same-site" | "cross-origin"];
export declare function createOriginAgentCluster(): readonly ["origin-agent-cluster", "?1"];
export declare function createReferrerPolicy({ policy, }?: ReferrerPolicyConfig): readonly ["referrer-policy", string];
export declare function createStrictTransportSecurity({ maxAge, includeSubDomains, preload, }?: StrictTransportSecurityConfig): readonly ["strict-transport-security", string];
export declare function createContentTypeOptions(): readonly ["x-content-type-options", "nosniff"];
export declare function createDnsPrefetchControl({ allow, }?: DnsPrefetchControlConfig): readonly ["x-dns-prefetch-control", "on" | "off"];
export declare function createDownloadOptions(): readonly ["x-download-options", "noopen"];
export declare function createFrameOptions({ action, }?: FrameOptionsConfig): readonly ["x-frame-options", "SAMEORIGIN" | "DENY"];
export declare function createPermittedCrossDomainPolicies({ permittedPolicies, }?: PermittedCrossDomainPoliciesConfig): readonly ["x-permitted-cross-domain-policies", "none" | "master-only" | "by-content-type" | "all"];
export declare function createXssProtection(): readonly ["x-xss-protection", "0"];
export default function nosecone({ contentSecurityPolicy, crossOriginEmbedderPolicy, crossOriginOpenerPolicy, crossOriginResourcePolicy, originAgentCluster, referrerPolicy, strictTransportSecurity, xContentTypeOptions, xDnsPrefetchControl, xDownloadOptions, xFrameOptions, xPermittedCrossDomainPolicies, xXssProtection, }?: NoseconeOptions): Headers;
/**
* Augment some Nosecone configuration with the values necessary for using the
* Vercel Toolbar.
*
* Follows the guidance at
* https://vercel.com/docs/workflow-collaboration/vercel-toolbar/managing-toolbar#using-a-content-security-policy
*
* @param config Base configuration for you application
* @returns Augmented configuration to allow Vercel Toolbar
*/
export declare function withVercelToolbar(config: NoseconeOptions): {
readonly contentSecurityPolicy: false | ContentSecurityPolicyConfig | undefined;
readonly crossOriginEmbedderPolicy: false | CrossOriginEmbedderPolicyConfig | undefined;
readonly crossOriginOpenerPolicy?: CrossOriginOpenerPolicyConfig | boolean;
readonly crossOriginResourcePolicy?: CrossOriginResourcePolicyConfig | boolean;
readonly originAgentCluster?: boolean;
readonly referrerPolicy?: ReferrerPolicyConfig | boolean;
readonly strictTransportSecurity?: StrictTransportSecurityConfig | boolean;
readonly xContentTypeOptions?: boolean;
readonly xDnsPrefetchControl?: DnsPrefetchControlConfig | boolean;
readonly xDownloadOptions?: boolean;
readonly xFrameOptions?: FrameOptionsConfig | boolean;
readonly xPermittedCrossDomainPolicies?: PermittedCrossDomainPoliciesConfig | boolean;
readonly xXssProtection?: boolean;
};