csp-helper/dist/index.d.ts

Helpers for managing Content Security Policy (CSP)

declare const CSP_HEADER_NAME = "Content-Security-Policy";

/**
 * Content Security Policy record type.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
 */
interface ContentSecurityPolicyRecord {
    'child-src': string;
    'connect-src': string;
    'default-src': string;
    'fenced-frame-src': string;
    'font-src': string;
    'frame-src': string;
    'img-src': string;
    'manifest-src': string;
    'media-src': string;
    'object-src': string;
    'script-src': string;
    'script-src-elem': string;
    'script-src-attr': string;
    'style-src': string;
    'style-src-elem': string;
    'style-src-attr': string;
    'worker-src': string;
    'base-uri': string;
    'sandbox': string;
    'form-action': string;
    'frame-ancestors': string;
    'report-to': string;
    'require-trusted-types-for ': string;
    'trusted-types': string;
    'upgrade-insecure-requests': '';
    /** @deprecated */
    'block-all-mixed-content': '';
    /** @deprecated */
    'prefetch-src': string;
    /** @deprecated */
    'report-uri': string;
}
/**
 * Content Security Policy directive type.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
 */
type ContentSecurityPolicyDirective = keyof ContentSecurityPolicyRecord;
/**
 * Content Security Policy config type.
 */
type ContentSecurityPolicyConfig = Partial<ContentSecurityPolicyRecord>;

interface CreateCspHeaderOptions {
    /**
     * Include header name in the output or not.
     *
     * @default false
     */
    includeHeaderName?: boolean;
    /**
     * Presets to include in the CSP header.
     *
     * @default []
     */
    presets?: ContentSecurityPolicyConfig[];
}
/**
 * Helper to create a Content-Security-Policy header.
 */
declare const createCspHeader: (config: ContentSecurityPolicyConfig, { includeHeaderName, presets }?: CreateCspHeaderOptions) => string;

/**
 * Helper to merge multiple CSP configs.
 */
declare const mergeCspConfigs: (configs: ContentSecurityPolicyConfig[]) => ContentSecurityPolicyConfig;

type ContentSecurityPolicyConfigSet = Partial<Record<ContentSecurityPolicyDirective, Set<string>>>;
/**
 * Helper to merge multiple CSP configs to configs set.
 */
declare const mergeCspConfigsToSet: (configs: ContentSecurityPolicyConfig[]) => ContentSecurityPolicyConfigSet;

/**
 * CSP preset for datadog intake URLs
 *
 * @see https://docs.datadoghq.com/integrations/content_security_policy_logs/?tab=firefox#intake-urls
 */
declare const CSP_PRESET_DATADOG_INTAKE_URLS: {
    'connect-src': string;
};
/**
 * CSP preset for datadog web worker
 *
 * @see https://docs.datadoghq.com/integrations/content_security_policy_logs/?tab=firefox#web-worker
 */
declare const CSP_PRESET_DATADOG_WEB_WORKER: {
    'worker-src': string;
};
/**
 * CSP preset for datadog CDN bundle URL
 *
 * @see https://docs.datadoghq.com/integrations/content_security_policy_logs/?tab=firefox#cdn-bundle-url
 */
declare const CSP_PRESET_DATADOG_CDN_BUNDLE_URL: {
    'script-src': string;
};

/**
 * CSP directives for google ads conversions
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#google_ads_conversions
 */
declare const CSP_PRESET_GOOGLE_ADS_CONVERSIONS: {
    'frame-src': string;
    'img-src': string;
    'script-src': string;
};
/**
 * CSP directives for google ads remarketing
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#google_ads_remarketing
 */
declare const CSP_PRESET_GOOGLE_ADS_REMARKETING: {
    'frame-src': string;
    'img-src': string;
    'script-src': string;
};
/**
 * CSP directives for google ads user data beacon
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#google_ads_user_data_beacon
 */
declare const CSP_PRESET_GOOGLE_ADS_USER_DATA_BEACON: {
    'frame-src': string;
    'script-src': string;
};

/**
 * CSP directives for google analytics 4
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#google_analytics_4_google_analytics
 */
declare const CSP_PRESET_GOOGLE_ANALYTICS_4: {
    'connect-src': string;
    'img-src': string;
    'script-src': string;
};
/**
 * CSP directives for google analytics 4 deployments using Google Signals
 *
 * This preset only includes the basic directives.
 *
 * You could add Google top-level domains (TLDs) to `connect-src` and `img-src` as needed.
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#google_analytics_4_google_analytics
 */
declare const CSP_PRESET_GOOGLE_ANALYTICS_4_GOOGLE_SIGNALS: {
    'connect-src': string;
    'frame-src': string;
    'img-src': string;
    'script-src': string;
};
/**
 * CSP directives for google analytics 4 deployments using Google Signals
 *
 * This preset includes the full list of Google top-level domains (TLDs) in `connect-src` and `img-src`.
 *
 * You may not need all of them if your site is not targeting all countries.
 *
 * The full list will make the CSP header too large, and you may need to update your server configs to allow large headers.
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#google_analytics_4_google_analytics
 */
declare const CSP_PRESET_GOOGLE_ANALYTICS_4_GOOGLE_SIGNALS_FULL_TLD: {
    'connect-src': string;
    'img-src': string;
};

/**
 * CSP directives for google fonts
 *
 * @see https://content-security-policy.com/examples/google-fonts/
 */
declare const CSP_PRESET_GOOGLE_FONTS: {
    'font-src': string;
    'style-src': string;
};

/**
 * CSP directives for google identity
 *
 * @see https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid#content_security_policy
 */
declare const CSP_PRESET_GOOGLE_IDENTITY: {
    'connect-src': string;
    'frame-src': string;
    'script-src': string;
    'style-src': string;
};

/**
 * CSP directives for google tag manager with nonce.
 *
 * Notice that `script-src 'nonce-<value>'` is not included, which should be added yourself.
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#enable_the_container_tag_to_use_csp
 */
declare const CSP_PRESET_GOOGLE_TAG_MANAGER_NONCE: {
    'connect-src': string;
    'img-src': string;
};
/**
 * CSP directives for google tag manager with 'unsafe-inline'
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#enable_the_container_tag_to_use_csp
 */
declare const CSP_PRESET_GOOGLE_TAG_MANAGER_UNSAFE_INLINE: {
    'connect-src': string;
    'img-src': string;
    'script-src': string;
};
/**
 * CSP directives for google tag manager with custom javascript variables
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#custom_javascript_variables
 */
declare const CSP_PRESET_GOOGLE_TAG_MANAGER_CUSTOM_JAVASCRIPT_VARIABLES: {
    'script-src': string;
};
/**
 * CSP directives for google tag manager preview mode
 *
 * Notice that the GTM preview mode is not properly maintained by Google:
 * - The docs and the actual requests are inconsistent. You may need to manually update the `img-src` and `style-src` directives.
 * - The css file and some requests of preview mode would be blocked by COEP due to lack of CORP header. You may need to disable COEP for preview mode.
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#preview_mode
 */
declare const CSP_PRESET_GOOGLE_TAG_MANAGER_PREVIEW_MODE: {
    'font-src': string;
    'img-src': string;
    'script-src': string;
    'style-src': string;
};

/**
 * CSP directives for google universal analytics
 *
 * @see https://developers.google.com/tag-platform/security/guides/csp#universal_analytics_google_analytics
 */
declare const CSP_PRESET_GOOGLE_UNIVERSAL_ANALYTICS: {
    'connect-src': string;
    'img-src': string;
    'script-src': string;
};

/**
 * CSP directives for hotjar
 *
 * @see https://help.hotjar.com/hc/en-us/articles/115011640307-Content-Security-Policies
 */
declare const CSP_PRESET_HOTJAR: {
    'connect-src': string;
    'font-src': string;
    'img-src': string;
    'script-src': string;
    'style-src': string;
};

/**
 * CSP directives for infogram embed
 *
 * @see https://support.infogram.com/hc/en-us/sections/360000124013-Embed
 */
declare const CSP_PRESET_INFOGRAM_EMBED: {
    'frame-src': string;
    'script-src': string;
};

/**
 * CSP directives for reddit embed
 */
declare const CSP_PRESET_REDDIT_EMBED: {
    'frame-src': string;
    'script-src': string;
};

/**
 * CSP directives for tiktok embed
 */
declare const CSP_PRESET_TIKTOK_EMBED: {
    'frame-src': string;
    'script-src': string;
};

/**
 * CSP directives for vimeo embed
 *
 * @see https://github.com/vimeo/player.js?tab=readme-ov-file#readme
 */
declare const CSP_PRESET_VIMEO_EMBED: {
    'connect-src': string;
    'frame-src': string;
    'img-src': string;
    'script-src': string;
};

/**
 * CSP directives for x embed
 */
declare const CSP_PRESET_X_EMBED: {
    'frame-src': string;
    'script-src': string;
};

/**
 * CSP directives for youtube embed
 */
declare const CSP_PRESET_YOUTUBE_EMBED: {
    'frame-src': string;
};

export { CSP_HEADER_NAME, CSP_PRESET_DATADOG_CDN_BUNDLE_URL, CSP_PRESET_DATADOG_INTAKE_URLS, CSP_PRESET_DATADOG_WEB_WORKER, CSP_PRESET_GOOGLE_ADS_CONVERSIONS, CSP_PRESET_GOOGLE_ADS_REMARKETING, CSP_PRESET_GOOGLE_ADS_USER_DATA_BEACON, CSP_PRESET_GOOGLE_ANALYTICS_4, CSP_PRESET_GOOGLE_ANALYTICS_4_GOOGLE_SIGNALS, CSP_PRESET_GOOGLE_ANALYTICS_4_GOOGLE_SIGNALS_FULL_TLD, CSP_PRESET_GOOGLE_FONTS, CSP_PRESET_GOOGLE_IDENTITY, CSP_PRESET_GOOGLE_TAG_MANAGER_CUSTOM_JAVASCRIPT_VARIABLES, CSP_PRESET_GOOGLE_TAG_MANAGER_NONCE, CSP_PRESET_GOOGLE_TAG_MANAGER_PREVIEW_MODE, CSP_PRESET_GOOGLE_TAG_MANAGER_UNSAFE_INLINE, CSP_PRESET_GOOGLE_UNIVERSAL_ANALYTICS, CSP_PRESET_HOTJAR, CSP_PRESET_INFOGRAM_EMBED, CSP_PRESET_REDDIT_EMBED, CSP_PRESET_TIKTOK_EMBED, CSP_PRESET_VIMEO_EMBED, CSP_PRESET_X_EMBED, CSP_PRESET_YOUTUBE_EMBED, type ContentSecurityPolicyConfig, type ContentSecurityPolicyDirective, type ContentSecurityPolicyRecord, type CreateCspHeaderOptions, createCspHeader, mergeCspConfigs, mergeCspConfigsToSet };