csp.ts

view source

Declarations
#

23 declarations

COLOR_SCHEME_SCRIPT_HASH
#

csp.ts view source

"sha256-QOxqn7EUzb3ydF9SALJoJGWSvywW9R0AfTDSenB83Z8=" import {COLOR_SCHEME_SCRIPT_HASH} from '@fuzdev/fuz_ui/csp.js';

create_csp_directives
#

csp.ts view source

(options?: CreateCspDirectivesOptions): CspDirectives import {create_csp_directives} from '@fuzdev/fuz_ui/csp.js';

Builds a CSP directives map for use with SvelteKit's kit.csp.directives option.

Restrictive by default; opt into specific permissions via extend (append) or overrides (replace). Designed to read as an audit log: every user-added source is named at exactly one site in the source code. Library defaults are inherited unless you opt out via replace_defaults.

Validation:

  • Unknown directive keys throw.
  • Extending a ['none'] directive throws (use replace_defaults/overrides to opt in).
  • null for replace_defaults (top-level or per-key) throws — omit the option for library defaults, pass {} to start blank, or use overrides to remove a specific directive.
  • null per-key in extend throws (use overrides for removal).
  • undefined per-key is treated as omitted in all three stages.
  • Non-object entries in extend (null, undefined, primitives) throw with a friendly error.
  • Output is validated to ensure 'none' never appears alongside other tokens, that no directive ends up with an empty array (use ['none'] to forbid all), and that every source array contains only strings.

Things like rendering to a string are out of scope and left to SvelteKit.

options

type CreateCspDirectivesOptions
default {}

returns

CspDirectives

CreateCspDirectivesOptions
#

csp.ts view source

CreateCspDirectivesOptions import type {CreateCspDirectivesOptions} from '@fuzdev/fuz_ui/csp.js';

Options for create_csp_directives.

The pipeline runs in three stages:

  1. replace_defaults sets the starting state (defaults to csp_directive_value_defaults).
  2. extend appends sources per directive, layered left to right.
  3. overrides replaces or removes per-directive values as a final pass.

replace_defaults?

Starting values per directive — *wholesale replaces* the library defaults.

  • Omitted: uses csp_directive_value_defaults (the curated library defaults).
  • Provided: exactly the directives you list, nothing else inherited. Anything not listed is absent from the starting state — including security defaults like default-src: 'none'. To tweak a single directive while keeping the rest, use extend (to append) or overrides (to replace per-key) instead.
  • {}: starts blank with no directives.

null is not accepted (top-level or per-key) — omit the option to use library defaults, pass {} to start blank, or use overrides to remove a specific directive.

Per-key undefined is treated as omitted (no-op).

type Partial<typeof csp_directive_value_defaults>

extend?

Sources to append per directive, layered left to right. Each entry is a partial map; values append to the result of replace_defaults and prior entries. Values are deduplicated within and across layers.

Only array-typed directives can be extended (boolean directives like upgrade-insecure-requests are excluded by the type). Throws if any entry attempts to extend a directive whose current value is ['none'] — use replace_defaults or overrides to opt into default-deny directives.

Per-key undefined is treated as omitted (no-op) — supports conditional patterns like {'connect-src': is_prod ? [API_URL] : undefined}. Per-key null throws — extend only appends; use overrides: { 'X': null } to remove a directive.

type ReadonlyArray<CspDirectiveSourcesMap>

overrides?

Final-pass per-directive overrides. Replaces the directive value or removes it entirely. Pass null to remove a directive from the output.

Highest precedence — wins over replace_defaults and extend.

Per-key undefined is treated as omitted (no-op) — distinct from null, which removes.

type { [K in CspDirective]?: CspDirectiveValue<K> | null; }

csp_directive_spec_by_name
#

csp.ts view source

Map<keyof CspDirectives, CspDirectiveSpec> import {csp_directive_spec_by_name} from '@fuzdev/fuz_ui/csp.js';

csp_directive_specs
#

csp_directive_value_defaults
#

csp.ts view source

Partial<{ "default-src": (CspSource | CspActionSource)[]; "script-src": (CspSource | CspActionSource)[]; "script-src-elem": CspSources; ... 20 more ...; sandbox: ("allow-downloads-without-user-activation" | ... 11 more ... | "allow-top-navigation-by-user-activation")[]; }> import {csp_directive_value_defaults} from '@fuzdev/fuz_ui/csp.js';

The library CSP directive defaults — directives enabled out of the box. Prioritizes safety but loosens around media and styles, relying on defense-in-depth. WASM compile is allowed ('wasm-unsafe-eval' on script-src and worker-src); eval is not.

Directives not listed here (report-to, require-trusted-types-for, trusted-types, sandbox) are intentionally absent by default — opt in via replace_defaults or overrides.

Customizable via CreateCspDirectivesOptions.replace_defaults.

CspActionSource
#

csp.ts view source

CspActionSource import type {CspActionSource} from '@fuzdev/fuz_ui/csp.js';

CspBaseSource
#

csp.ts view source

CspBaseSource import type {CspBaseSource} from '@fuzdev/fuz_ui/csp.js';

CspCryptoSource
#

csp.ts view source

`nonce-${string}` | `sha256-${string}` | `sha384-${string}` | `sha512-${string}` import type {CspCryptoSource} from '@fuzdev/fuz_ui/csp.js';

CspDirective
#

csp.ts view source

keyof CspDirectives import type {CspDirective} from '@fuzdev/fuz_ui/csp.js';

CspDirectives
#

csp.ts view source

CspDirectives import type {CspDirectives} from '@fuzdev/fuz_ui/csp.js';

sandbox?

type Array< | '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' >

CspDirectiveSourcesMap
#

csp.ts view source

CspDirectiveSourcesMap import type {CspDirectiveSourcesMap} from '@fuzdev/fuz_ui/csp.js';

Per-directive map of source arrays — accepted as extend layer entries. Excludes directives like 'upgrade-insecure-requests' (boolean) that can't be appended to.

CspDirectiveSpec
#

csp.ts view source

CspDirectiveSpec import type {CspDirectiveSpec} from '@fuzdev/fuz_ui/csp.js';

name

type CspDirective

fallback

type Array<CspDirective> | null

fallback_of

type Array<CspDirective> | null

CspDirectiveValue
#

csp.ts view source

CspDirectiveValue<T> import type {CspDirectiveValue} from '@fuzdev/fuz_ui/csp.js';

generics

CspDirectiveValue<T extends CspDirective>
T
constraint CspDirective

CspFrameSource
#

csp.ts view source

CspFrameSource import type {CspFrameSource} from '@fuzdev/fuz_ui/csp.js';

CspHostNameScheme
#

csp.ts view source

CspHostNameScheme import type {CspHostNameScheme} from '@fuzdev/fuz_ui/csp.js';

CspHostProtocolSchemes
#

csp.ts view source

CspHostProtocolSchemes import type {CspHostProtocolSchemes} from '@fuzdev/fuz_ui/csp.js';

CspHostSource
#

csp.ts view source

`${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}`... import type {CspHostSource} from '@fuzdev/fuz_ui/csp.js';

CspPortScheme
#

csp.ts view source

CspPortScheme import type {CspPortScheme} from '@fuzdev/fuz_ui/csp.js';

CspSchemeSource
#

csp.ts view source

CspSchemeSource import type {CspSchemeSource} from '@fuzdev/fuz_ui/csp.js';

CspSource
#

CspSources
#

csp.ts view source

CspSources import type {CspSources} from '@fuzdev/fuz_ui/csp.js';

parse_csp_directive
#

csp.ts view source

(directive: unknown): keyof CspDirectives | null import {parse_csp_directive} from '@fuzdev/fuz_ui/csp.js';

directive

type unknown

returns

keyof CspDirectives | null

Imported by
#