csp-typed-directives
Version:
Provides type information for all CSP directives and related headers' directives; as well as a basic utility funtion that helps convert the typed properties to the header content's policy string.
233 lines (230 loc) • 13.2 kB
TypeScript
declare const schemeSource: readonly ["http:", "https:", "data:", "mediastream:", "blob:", "filesystem:"];
declare type SchemeSource = typeof schemeSource[number];
declare type OptionalPath = `${HttpDelineators}${string}` | '';
declare type UrlString = `${HostSource}${OptionalPath}`;
declare type HostProtocolSchemes = `${string}://` | '';
declare type PortScheme = `:${number}` | '' | ':*';
/** Can actually be any string, but typed more explicitly to
* restrict the combined optional types of Source from collapsing to just bing `string` */
declare type HostNameScheme = `${string}.${string}` | `localhost`;
declare type HostSource = `${HostProtocolSchemes}${HostNameScheme}${PortScheme}`;
declare const validCrypto: readonly ["nonce", "sha256", "sha384", "sha512"];
declare type ValidCrypto$1 = typeof validCrypto[number];
declare type CryptoSources = `${ValidCrypto$1}-${string}`;
declare const httpDelineators: readonly ["/", "?", "#", "\\"];
declare type HttpDelineators = typeof httpDelineators[number];
declare type UriPath = `${HttpDelineators}${string}`;
declare const baseSources: readonly ["self", "unsafe-eval", "unsafe-hashes", "unsafe-inline", "none", "*"];
declare type BaseSources = typeof baseSources[number];
declare type Source = BaseSources | HostSource | SchemeSource | CryptoSources;
declare type Sources = Source | Source[];
declare const referrerHeaderOptions: readonly ["no-referrer", "no-referrer-when-downgrade", "origin", "origin-when-cross-origin", "same-origin", "strict-origin", "strict-origin-when-cross-origin", "unsafe-url", "none"];
declare type ReferrerHeaderOptions = typeof referrerHeaderOptions[number];
declare type ChildDirectives = {
'child-src'?: Sources;
'frame-src'?: Sources;
'worker-src'?: Sources;
};
declare type SourceDirectives = {
'connect-src'?: Sources;
'default-src'?: ActionSource | ActionSource[];
'font-src'?: Sources;
'frame-src'?: Sources;
'img-src'?: Sources;
'manifest-src'?: Sources;
'media-src'?: Sources;
'object-src'?: Sources;
'prefetch-src'?: Sources;
'script-src'?: ActionSource | ActionSource[];
'script-src-elem'?: Sources;
'script-src-attr'?: Sources;
'style-src'?: Sources;
'style-src-elem'?: Sources;
'style-src-attr'?: Sources;
};
declare const sandboxDirectives: readonly ["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"];
declare type SandboxOption = typeof sandboxDirectives[number];
declare type PluginSource = `${string}/${string}` | 'none';
declare type DocumentDirectives = {
/**
* Restricts the URLs which can be used in a document's <base> element. */
'base-uri'?: ActionSource | ActionSource[];
/**
* Restricts the set of plugins that can be embedded into a document by
* limiting the types of resources which can be loaded.
* @deprecated */
'plugin-types'?: PluginSource | PluginSource[];
/**
* Enables a sandbox for the requested resource similar to the <iframe> sandbox attribute. */
'sandbox'?: SandboxOption;
};
declare const actionSource: readonly ["strict-dynamic", "report-sample"];
declare type ActionSource = Source | typeof actionSource[number];
declare type FrameSource = HostSource | SchemeSource | 'self' | 'none';
/**
* Navigation directives govern to which locations a user can navigate or submit a form, for example.
*/
declare type NavigationDirectives = {
/**
* Restricts the URLs which can be used as the target of a form submissions from a given context. */
'form-action'?: ActionSource | ActionSource[];
/**
* Specifies valid parents that may embed a page using <frame>, <iframe>, <object>, <embed>, or <applet>. */
'frame-ancestors'?: FrameSource | FrameSource[];
/**
* Restricts the URLs to which a document can initiate navigation by any means,
* including <form> (if form-action is not specified), <a>, window.location, window.open, etc.
* @experimental */
'navigate-to'?: ActionSource | ActionSource[];
};
/**
* Reporting directives control the reporting process of CSP violations.
* See also the Content-Security-Policy-Report-Only header.
*/
declare type ReportingDirectives = {
/** @deprecated */
'report-uri'?: UriPath;
/** @experimental */
'report-to'?: ReportTo['group'];
};
/** Disallows using strings with DOM XSS injection sink functions,
* and requires matching types created by Trusted Type policies. */
declare const requireTrustedTypePolicy: readonly ["script"];
declare type RequireTrustedTypePolicy = typeof requireTrustedTypePolicy[number];
declare const trustedTypesPolicy: readonly ["none", "allow-duplicates", "*"];
declare type TrustedTypesPolicy = typeof trustedTypesPolicy[number] | string;
declare const sriPolicy: readonly ["script", "style", "script style"];
declare type SriPolicy = typeof sriPolicy[number];
declare type OtherDirectives = {
/** Prevents loading any assets using HTTP when the page is loaded using HTTPS.
@deprecated */
'block-all-mixed-content'?: boolean;
/** Used to specify information in the Referer (sic) header for links away from a page.
* Use the Referrer-Policy header instead.
@deprecated */
'referrer'?: ReferrerHeaderOptions;
/** Requires the use of SRI for scripts or styles on the page.
@deprecated */
'require-sri-for'?: SriPolicy;
/** Enforces Trusted Types at the DOM XSS injection sinks. */
'require-trusted-types-for'?: RequireTrustedTypePolicy;
/** Used to specify an allow-list of Trusted Types policies.
* Trusted Types allows applications to lock down
* DOM XSS injection sinks to only accept non-spoofable,
* typed values in place of strings. */
'trusted-types'?: TrustedTypesPolicy | TrustedTypesPolicy[];
/** Instructs user agents to treat all of a site's insecure URLs (those served over HTTP)
* as though they have been replaced with secure URLs (those served over HTTPS).
* This directive is intended for web sites with large numbers of insecure legacy
* URLs that need to be rewritten. */
'upgrade-insecure-requests'?: boolean;
};
declare const directiveValuesByCategory: {
readonly hostSource: readonly [{
readonly displayName: "Hostname/URL Source";
readonly consumes: {
readonly Port: "number";
readonly Hostname: "string";
readonly Protocol: "string://";
};
readonly compose: (args: {
'Port'?: number;
'Hostname'?: string;
'Protocol'?: HostProtocolSchemes;
}) => `${string}.${string}` | "localhost" | `${string}.${string}:${number}` | `${string}.${string}:*` | `localhost:${number}` | "localhost:*" | `${string}://${string}.${string}` | `${string}://${string}.${string}:${number}` | `${string}://${string}.${string}:*` | `${string}://localhost` | `${string}://localhost:${number}` | `${string}://localhost:*`;
}];
readonly schemeSource: readonly ["http:", "https:", "data:", "mediastream:", "blob:", "filesystem:"];
readonly cryptoSource: readonly [{
readonly displayName: "Crypto Nonce/Hash Source";
readonly consumes: {
readonly Hash: "string";
readonly Algorithm: readonly ["nonce", "sha256", "sha384", "sha512"];
};
readonly compose: (args: {
Hash: string;
Algorithm: ValidCrypto$1;
}) => `nonce-${string}` | `sha256-${string}` | `sha384-${string}` | `sha512-${string}`;
}];
readonly baseSources: readonly ["self", "unsafe-eval", "unsafe-hashes", "unsafe-inline", "none", "*"];
readonly primitiveSourceBool: readonly [true, false];
readonly primitiveSourceString: readonly [{
readonly displayName: "Any String";
readonly consumes: {
readonly String: "string";
};
readonly compose: (args: {
String: string;
}) => string;
}];
readonly trustedTypesPolicy: readonly ["none", "allow-duplicates", "*"];
readonly requireTrustedTypePolicy: readonly ["script"];
readonly sriPolicy: readonly ["script", "style", "script style"];
readonly referrerHeaderOptions: readonly ["no-referrer", "no-referrer-when-downgrade", "origin", "origin-when-cross-origin", "same-origin", "strict-origin", "strict-origin-when-cross-origin", "unsafe-url", "none"];
readonly uriPath: readonly [{
readonly displayName: "URI Source";
readonly consumes: {
readonly 'Beginning Delineator': readonly ["/", "?", "#", "\\"];
readonly 'Remaining Path': "string";
};
readonly compose: (args: {
'Beginning Delineator': HttpDelineators;
'Remaining Path': string;
}) => `/${string}` | `?${string}` | `#${string}` | `\\${string}`;
}];
readonly actionSource: readonly ["strict-dynamic", "report-sample"];
readonly pluginSource: readonly [{
readonly displayName: "Plugin MIME Type Source";
readonly consumes: {
readonly 'MIME Category': "string";
readonly 'MIME Implementation': "string";
};
readonly compose: (args: {
'MIME Category': string;
'MIME Implementation': string;
}) => PluginSource;
}, "none"];
readonly frameSource: readonly ["self", "none"];
readonly sandboxDirectives: readonly ["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"];
};
declare const directiveMap: Readonly<Record<(keyof Directives), Readonly<(keyof typeof directiveValuesByCategory)[]>>>;
declare type Directives = ChildDirectives & SourceDirectives & OtherDirectives & ReportingDirectives & NavigationDirectives & DocumentDirectives;
declare type ReportTo = {
group: string;
max_age: number;
endpoints: {
url: UrlString;
}[];
};
declare type ValidSource = Source;
declare type ReportTos = ReportTo | ReportTo[];
declare const ValidHashes: readonly ["sha256", "sha384", "sha512"];
declare const ValidCrypto: readonly ["nonce", "sha256", "sha384", "sha512"];
declare const directiveNamesList: ("child-src" | "frame-src" | "worker-src" | "connect-src" | "default-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" | "block-all-mixed-content" | "referrer" | "require-sri-for" | "require-trusted-types-for" | "trusted-types" | "upgrade-insecure-requests" | "report-uri" | "report-to" | "form-action" | "frame-ancestors" | "navigate-to" | "base-uri" | "plugin-types" | "sandbox")[];
declare type DirectiveName = keyof typeof directiveMap;
declare type DirectiveValue = typeof directiveMap[DirectiveName];
declare type CategoryValue = FlatArray<(typeof directiveValuesByCategory[DirectiveValue[number]]), 1>;
declare type DirectiveResult = {
values: Partial<CategoryValue>[];
categories: DirectiveValue;
};
declare const DirectiveMap: Map<"child-src" | "frame-src" | "worker-src" | "connect-src" | "default-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" | "block-all-mixed-content" | "referrer" | "require-sri-for" | "require-trusted-types-for" | "trusted-types" | "upgrade-insecure-requests" | "report-uri" | "report-to" | "form-action" | "frame-ancestors" | "navigate-to" | "base-uri" | "plugin-types" | "sandbox", DirectiveResult>;
declare const referrerHeaderOptionsList: readonly ["no-referrer", "no-referrer-when-downgrade", "origin", "origin-when-cross-origin", "same-origin", "strict-origin", "strict-origin-when-cross-origin", "unsafe-url", "none"];
declare type DirectivesObj = Directives;
declare type ReportToObj = ReportTo;
declare type ReferrerHeaderOptionsList = ReferrerHeaderOptions;
declare type CspDirectiveHeaders = {
'Content-Security-Policy-Report-Only': string;
'Content-Security-Policy': string;
'Report-To': string;
'Referrer-Policy': string;
};
declare class CspDirectives {
CSP: Directives;
ReportOnly: Directives | false;
ReportTo: ReportTos;
ReferrerHeader: ReferrerHeaderOptions;
constructor(csp?: Directives, sendReportsTo?: ReportTos, reportSubset?: Directives, referrerHeaderOverride?: ReferrerHeaderOptions);
checkReportTo(): void;
getHeaders(): CspDirectiveHeaders;
}
export { CspDirectiveHeaders, CspDirectives, DirectiveMap, DirectivesObj, ReferrerHeaderOptionsList, ReportToObj, ValidCrypto, ValidHashes, ValidSource, directiveNamesList, referrerHeaderOptionsList };