@fuzdev/fuz_ui 0.191.3 → 0.192.0

package/dist/csp.d.ts

@@ -1,121 +1,112 @@
-import type { ArrayElement, Defined } from '@fuzdev/fuz_util/types.js';
+import type { Defined } from '@fuzdev/fuz_util/types.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.
+ */
+export type CspDirectiveSourcesMap = {
+    [K in CspDirective as CspDirectives[K] extends ReadonlyArray<any> ? K : never]?: CspDirectives[K];
+};
+/**
+ * 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.
+ */
 export interface CreateCspDirectivesOptions {
     /**
-     * Override or transform specific directives.
-     * Returning `null` or `undefined` from a transform function will remove the directive.
+     * 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).
      */
-    directives?: {
-        [K in CspDirective]?: CspDirectiveValue<K> | null | ((value: CspDirectiveValue<K>) => CspDirectiveValue<K> | null);
-    };
-    /**
-     * Sources to include based on their trust levels.
-     */
-    trusted_sources?: Array<CspSourceSpec>;
+    replace_defaults?: Partial<typeof csp_directive_value_defaults>;
     /**
-     * Override default values for specific directives,
-     * merging with `value_defaults_base` (or replacing if that directive is null in the base).
+     * 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.
      */
-    value_defaults?: Partial<typeof csp_directive_value_defaults>;
+    extend?: ReadonlyArray<CspDirectiveSourcesMap>;
     /**
-     * Base values for directive defaults.
-     * Set to `null` or `{}` to start with no defaults.
-     * Defaults to `csp_directive_value_defaults`.
+     * 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.
      */
-    value_defaults_base?: Partial<typeof csp_directive_value_defaults> | null;
-    /**
-     * Override trust requirements for specific directives,
-     * merging with `required_trust_defaults_base` (or replacing if that directive is null in the base).
-     */
-    required_trust_defaults?: Partial<typeof csp_directive_required_trust_defaults>;
-    /**
-     * Base values for directive trust requirements.
-     * Set to `null` or `{}` to start with no trust requirements.
-     * Defaults to `csp_directive_required_trust_defaults`.
-     */
-    required_trust_defaults_base?: Partial<typeof csp_directive_required_trust_defaults> | null;
+    overrides?: {
+        [K in CspDirective]?: CspDirectiveValue<K> | null;
+    };
 }
 /**
- * This is designed for compatibility with SvelteKit
- * and maps to the `KitConfig` `directives` option.
- * The goal is to provide an ergonomic, modern, and safe API
- * for Content Security Policy (CSP) creation
- * that's simple to write and audit, and isn't error-prone.
+ * Builds a CSP directives map for use with SvelteKit's `kit.csp.directives` option.
  *
- * Things like validation and rendering to a string
- * are out of scope and left to SvelteKit.
+ * 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.
  */
-export declare function create_csp_directives(options?: CreateCspDirectivesOptions): CspDirectives;
+export declare const create_csp_directives: (options?: CreateCspDirectivesOptions) => CspDirectives;
 export type CspDirective = keyof CspDirectives;
 export declare const parse_csp_directive: (directive: unknown) => CspDirective | null;
 export type CspDirectiveValue<T extends CspDirective> = Defined<CspDirectives[T]>;
-export declare const csp_trust_levels: readonly ["low", "medium", "high"];
-/**
- * Numeric values for CSP trust levels. See `csp_trust_levels`.
- * Lower is less trusted.
- * Includes `undefined` in the type for safety.
- */
-export declare const csp_trust_level_value: Record<CspTrustLevel, number | undefined>;
+export declare const COLOR_SCHEME_SCRIPT_HASH = "sha256-QOxqn7EUzb3ydF9SALJoJGWSvywW9R0AfTDSenB83Z8=";
 /**
- * Trust levels for CSP sources.
- *
- * With the base defaults, trust levels roughly correspond to:
+ * 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.
  *
- * - `low` – Passive resources only (no script execution, no styling or UI control).
- * 		Examples: `img-src`, `font-src`.
- * - `medium` – Content that may affect layout, styling, or embed external browsing contexts,
- *    but cannot directly run code in the page's JS execution environment or
- * 		perform other high-risk actions. Examples: `style-src`, `frame-src`, `frame-ancestors`.
- * - `high` – Sources that can execute code in the page's context or open powerful network
- *    channels. Examples: `script-src`, `connect-src`, `child-src`.
- * - `null` – No trust. This is used for directives that don't support sources.
+ * 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`.
  */
-export type CspTrustLevel = ArrayElement<typeof csp_trust_levels>;
-/**
- * Validates and extracts a CSP trust level from an unknown value.
- */
-export declare const parse_csp_trust_level: (trust: unknown) => CspTrustLevel | null;
-export interface CspSourceSpec {
-    source: CspSource;
-    trust?: CspTrustLevel;
-    directives?: Array<CspDirective>;
-}
+export declare const csp_directive_value_defaults: Partial<{
+    [K in CspDirective]: CspDirectiveValue<K>;
+}>;
 export interface CspDirectiveSpec {
     name: CspDirective;
     fallback: Array<CspDirective> | null;
     fallback_of: Array<CspDirective> | null;
 }
-/**
- * Determines if a granted trust level is sufficient to satisfy a required trust level.
- *
- * Trust levels have the following hierarchy:
- * - 'high' sources can be used in high, medium, and low trust directives (highest privilege)
- * - 'medium' sources can be used in medium and low trust directives
- * - 'low' sources can only be used in low trust directives (lowest privilege)
- */
-export declare const is_csp_trusted: (required_trust: CspTrustLevel | null | undefined, granted_trust: CspTrustLevel | null | undefined) => boolean;
-export declare const COLOR_SCHEME_SCRIPT_HASH = "sha256-QOxqn7EUzb3ydF9SALJoJGWSvywW9R0AfTDSenB83Z8=";
-/**
- * The base CSP directive defaults.
- * Prioritizes safety but loosens around media and styles, relying on defense-in-depth.
- * Customizable via `CreateCspDirectivesOptions`.
- */
-export declare const csp_directive_value_defaults: Record<CspDirective, CspDirectiveValue<CspDirective> | null>;
-/**
- * Sources that meet this trust requirement are included for it by default.
- * If null, no trusted sources are added to the directive automatically.
- * Directives that don't support sources or default to `['none']` are null.
- *
- * Feedback is welcome, please see the issues - https://github.com/fuzdev/fuz_ui/issues
- */
-export declare const csp_directive_required_trust_defaults: Record<CspDirective, CspTrustLevel | null>;
 /**
  * Static data descriptors for the CSP directives.
  * Fuz excludes deprecated directives, so those are intentionally omitted,
  * but any newer missing directives are bugs.
  *
- * Could be co-located but is currently here to keep that module smaller.
- *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy}
  */
 export declare const csp_directive_specs: Array<CspDirectiveSpec>;

package/dist/csp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csp.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/csp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"csp.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/csp.ts"],"names":[],"mappings":"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"}

package/dist/csp.js

@@ -1,155 +1,180 @@
 /**
- * This is designed for compatibility with SvelteKit
- * and maps to the `KitConfig` `directives` option.
- * The goal is to provide an ergonomic, modern, and safe API
- * for Content Security Policy (CSP) creation
- * that's simple to write and audit, and isn't error-prone.
+ * Builds a CSP directives map for use with SvelteKit's `kit.csp.directives` option.
  *
- * Things like validation and rendering to a string
- * are out of scope and left to SvelteKit.
+ * 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.
  */
-export function create_csp_directives(options = {}) {
-    const { directives: directives_option, trusted_sources, value_defaults_base = csp_directive_value_defaults, value_defaults: value_defaults_option, required_trust_defaults_base = csp_directive_required_trust_defaults, required_trust_defaults: required_trust_defaults_option, } = options;
+export const create_csp_directives = (options = {}) => {
+    const { replace_defaults = csp_directive_value_defaults, extend, overrides } = options;
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (replace_defaults === null) {
+        throw new Error(`Invalid value 'null' for options.replace_defaults. ` +
+            `Omit the option to use library defaults, or pass {} to start with no directives.`);
+    }
     const directives = {};
-    // Shallowly merge any provided defaults with the base defaults
-    const value_defaults = { ...value_defaults_base, ...value_defaults_option };
-    // Merge required trust defaults with the base
-    const required_trust_defaults = {
-        ...required_trust_defaults_base,
-        ...required_trust_defaults_option,
+    // `Object.entries` widens to `[string, unknown]` and TS can't re-narrow per-key, so
+    // writes via the validated `directive` need a single trusted-bridge cast — kept inside
+    // this helper so the call sites stay free of type assertions. Clones arrays so callers
+    // don't have to worry about user-supplied arrays leaking into the output.
+    const assign = (directive, value) => {
+        directives[directive] = Array.isArray(value)
+            ? [...value]
+            : value;
     };
-    // Apply defaults from directive specs
-    for (const spec of csp_directive_specs) {
-        const default_value = value_defaults[spec.name];
-        if (default_value == null)
-            continue; // omit null and undefined
-        directives[spec.name] = Array.isArray(default_value)
-            ? [...default_value]
-            : default_value;
-    }
-    // Get trust requirements (with overrides applied)
-    const trust_requirements = new Map();
-    for (const spec of csp_directive_specs) {
-        const required_trust = required_trust_defaults[spec.name];
-        if (required_trust == null)
-            continue; // omit null and undefined
-        trust_requirements.set(spec.name, required_trust);
-    }
-    // Validate trusted_sources directives
-    if (trusted_sources?.length) {
-        for (const spec of trusted_sources) {
-            if (spec.directives) {
-                for (const directive of spec.directives) {
-                    if (parse_csp_directive(directive) === null) {
-                        throw new Error(`Invalid directive in trusted_sources: ${directive}`);
-                    }
+    // Stage 1: starting state from `replace_defaults`.
+    // `{}` starts blank — every directive must come from `extend`/`overrides`.
+    for_each_directive(replace_defaults, 'replace_defaults', (directive, value) => {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (value === null) {
+            throw new Error(`Invalid value 'null' for directive '${directive}' in options.replace_defaults. ` +
+                `Omit the key instead, or use \`overrides: { '${directive}': null }\` to remove.`);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (value === undefined)
+            return;
+        assign(directive, value);
+    });
+    // Stage 2: append sources per layer in `extend`.
+    if (extend?.length) {
+        for (const layer of extend) {
+            for_each_directive(layer, 'extend', (directive, value) => {
+                // `undefined` is treated as omitted, matching `replace_defaults`/`overrides`.
+                // Lets callers write `{'connect-src': cond ? [API] : undefined}` naturally.
+                if (value === undefined)
+                    return;
+                // `null` is meaningful enough to deserve its own error — users reaching for null
+                // in extend almost always want removal, which lives on `overrides`.
+                if (value === null) {
+                    throw new Error(`Cannot extend directive '${directive}' with null. ` +
+                        `extend can only append sources — to remove a directive from the output, ` +
+                        `use \`overrides: { '${directive}': null }\`.`);
                 }
-            }
+                if (!Array.isArray(value)) {
+                    throw new Error(`Cannot extend directive '${directive}': value must be an array of sources, got ${typeof value}.`);
+                }
+                if (!value.length)
+                    return;
+                const current = directives[directive];
+                if (is_none(current)) {
+                    throw new Error(`Cannot extend directive '${directive}' while its current value is ['none']. ` +
+                        `The pipeline runs replace_defaults → extend → overrides, so an \`overrides\` ` +
+                        `entry for '${directive}' cannot rescue this — extend sees the ['none'] starting ` +
+                        `value first. Opt in via \`replace_defaults: { '${directive}': [...] }\` or move ` +
+                        `the sources into \`overrides: { '${directive}': [...] }\`.`);
+                }
+                if (current === undefined) {
+                    assign(directive, [...new Set(value)]);
+                }
+                else if (Array.isArray(current)) {
+                    assign(directive, [...new Set([...current, ...value])]);
+                }
+                else {
+                    throw new Error(`Cannot extend directive '${directive}': it has a non-array value.`);
+                }
+            });
         }
     }
-    // Apply trusted sources to directives
-    if (trusted_sources?.length) {
-        for (const [key, value] of Object.entries(directives)) {
-            const directive = parse_csp_directive(key);
-            if (directive === null) {
-                throw new Error(`Invalid directive in options.directives: ${key}`);
-            }
-            // Skip if directive is ['none'] or not an array
-            if (is_none_directive(value) || !Array.isArray(value)) {
-                continue;
+    // Stage 3: final-pass `overrides` — replace value or remove key.
+    if (overrides) {
+        for_each_directive(overrides, 'overrides', (directive, value) => {
+            if (value === null) {
+                delete directives[directive]; // eslint-disable-line @typescript-eslint/no-dynamic-delete
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             }
-            // Get required trust for this directive
-            const required_trust = trust_requirements.get(directive);
-            if (required_trust == null)
-                continue;
-            // Add matching sources - separate the filtering into trust-based and directive-based inclusion
-            const sources_to_add = trusted_sources
-                .filter((spec) => {
-                // Check for explicit inclusion in directives list
-                const explicitly_included = spec.directives?.includes(directive) ?? false;
-                // Check for trust level based inclusion
-                const has_trust_level = spec.trust !== undefined;
-                const include_by_trust = has_trust_level && is_csp_trusted(required_trust, spec.trust);
-                // Include the source if either condition is met
-                return explicitly_included || include_by_trust;
-            })
-                .map((spec) => spec.source);
-            if (sources_to_add.length > 0) {
-                directives[directive] = [...value, ...sources_to_add];
+            else if (value !== undefined) {
+                assign(directive, value);
             }
-        }
+        });
     }
-    // Apply directive overrides/transformations
-    if (directives_option) {
-        for (const [key, value_or_fn] of Object.entries(directives_option)) {
-            const directive = parse_csp_directive(key);
-            if (directive === null) {
-                throw new Error(`Invalid directive in options.directives: ${key}`);
-            }
-            const current = directives[directive];
-            const result = typeof value_or_fn === 'function' ? value_or_fn(current) : value_or_fn;
-            // Handle `undefined` too just in case
-            if (result == null) {
-                delete directives[directive]; // eslint-disable-line @typescript-eslint/no-dynamic-delete
-            }
-            else {
-                directives[directive] = structuredClone(result);
+    // Stage 4: output validation — empty arrays and mixed `'none'` are invalid CSP.
+    for (const [key, value] of Object.entries(directives)) {
+        if (typeof value === 'boolean')
+            continue;
+        if (!Array.isArray(value)) {
+            throw new Error(`Directive '${key}' has an invalid value: expected an array of sources or a boolean, ` +
+                `got ${value === null ? 'null' : typeof value}.`);
+        }
+        if (value.length === 0) {
+            throw new Error(`Directive '${key}' has an empty array. ` +
+                `Use ['none'] to forbid all sources, or omit the directive entirely.`);
+        }
+        // Element-level type check — the `CspSource` template-string type gates this at the
+        // type layer, but `as any` callers can slip non-strings through. A non-string source
+        // would render as `undefined` / `[object Object]` in the emitted CSP header.
+        for (let i = 0; i < value.length; i++) {
+            const v = value[i];
+            if (typeof v !== 'string') {
+                throw new Error(`Directive '${key}' has a non-string source at index ${i}: got ${v === null ? 'null' : typeof v}.`);
             }
         }
+        if (value.length > 1 && value.includes('none')) {
+            throw new Error(`Directive '${key}' has 'none' alongside other tokens (${value.join(', ')}). ` +
+                `'none' must appear alone in CSP.`);
+        }
     }
     return directives;
-}
+};
 export const parse_csp_directive = (directive) => typeof directive === 'string' && csp_directive_spec_by_name.has(directive)
     ? directive
     : null;
-export const csp_trust_levels = ['low', 'medium', 'high'];
-/**
- * Numeric values for CSP trust levels. See `csp_trust_levels`.
- * Lower is less trusted.
- * Includes `undefined` in the type for safety.
- */
-export const csp_trust_level_value = {
-    low: 0,
-    medium: 1,
-    high: 2,
-};
-/**
- * Validates and extracts a CSP trust level from an unknown value.
- */
-export const parse_csp_trust_level = (trust) => csp_trust_levels.includes(trust) ? trust : null;
+const is_none = (value) => Array.isArray(value) && value.length === 1 && value[0] === 'none';
 /**
- * Determines if a granted trust level is sufficient to satisfy a required trust level.
+ * Iterate over a per-directive options map, validating that every key is a known directive.
+ * Throws if any key fails to parse as a `CspDirective`, mentioning `source_label` so the
+ * error pinpoints which option (`replace_defaults`, `extend`, or `overrides`) was bad.
  *
- * Trust levels have the following hierarchy:
- * - 'high' sources can be used in high, medium, and low trust directives (highest privilege)
- * - 'medium' sources can be used in medium and low trust directives
- * - 'low' sources can only be used in low trust directives (lowest privilege)
+ * Also guards against non-object `source` values (e.g. `extend: [undefined]`, `extend: ['oops']`)
+ * so callers get a friendly library error instead of a cryptic native `TypeError` from
+ * `Object.entries`.
  */
-export const is_csp_trusted = (required_trust, granted_trust) => {
-    const required_value = required_trust && csp_trust_level_value[required_trust];
-    const granted_value = granted_trust && csp_trust_level_value[granted_trust];
-    if (required_value == null || granted_value == null) {
-        return false;
+const for_each_directive = (source, source_label, fn) => {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (source === null || typeof source !== 'object') {
+        const got = source === null ? 'null' : typeof source; // eslint-disable-line @typescript-eslint/no-unnecessary-condition
+        throw new Error(`Invalid entry in options.${source_label}: expected an object, got ${got}.`);
+    }
+    for (const [key, value] of Object.entries(source)) {
+        const directive = parse_csp_directive(key);
+        if (directive === null) {
+            throw new Error(`Invalid directive in options.${source_label}: ${key}`);
+        }
+        fn(directive, value);
     }
-    // A source with higher trust privilege (higher value)
-    // can be used in a directive with less privilege (lower value).
-    return granted_value >= required_value;
 };
-/**
- * Helper to check if a directive value is `['none']`,
- * or more precisely for robustness with malformed values, checks for an array with `'none'`.
- */
-const is_none_directive = (value) => Array.isArray(value) && value.includes('none');
 export const COLOR_SCHEME_SCRIPT_HASH = 'sha256-QOxqn7EUzb3ydF9SALJoJGWSvywW9R0AfTDSenB83Z8=';
 /**
- * The base CSP directive defaults.
+ * The library CSP directive defaults — directives enabled out of the box.
  * Prioritizes safety but loosens around media and styles, relying on defense-in-depth.
- * Customizable via `CreateCspDirectivesOptions`.
+ * 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`.
  */
 export const csp_directive_value_defaults = {
     'default-src': ['none'],
-    'script-src': ['self', COLOR_SCHEME_SCRIPT_HASH], // Eval is opt-in, scripting is locked down except for self and the color scheme loader script
-    'script-src-elem': ['self', COLOR_SCHEME_SCRIPT_HASH], // Block script elements except for self and the color scheme loader
+    // `'wasm-unsafe-eval'` permits WASM compile/instantiate only — `eval` and `new Function`
+    // remain blocked. Needed for `@fuzdev/fuz_util/hash_blake3` and any other WASM in the page.
+    // Pre-2022 browsers ignore the keyword and block WASM; if you need them, override with `'unsafe-eval'`.
+    'script-src': ['self', 'wasm-unsafe-eval', COLOR_SCHEME_SCRIPT_HASH],
+    'script-src-elem': ['self', COLOR_SCHEME_SCRIPT_HASH], // Block script elements except for self and the color scheme loader (WASM compile is gated by script-src, not script-src-elem)
     'script-src-attr': ['none'], // Block scripts in HTML attributes
     'style-src': ['self', 'unsafe-inline'], // Main style directive (uses unsafe-inline but network connections are disallowed by other directives)
     'style-src-elem': ['self', 'unsafe-inline'], // Style elements (standalone stylesheets)
@@ -163,55 +188,17 @@ export const csp_directive_value_defaults = {
     'frame-src': ['self'], // Frames/iframes
     'frame-ancestors': ['self'], // Control what can embed this page
     'form-action': ['self'], // Form submission targets
-    'worker-src': ['self', 'blob:'], // Web workers
+    // `'wasm-unsafe-eval'` mirrors the script-src allowance so WASM compiled inside a Web Worker also works.
+    'worker-src': ['self', 'blob:', 'wasm-unsafe-eval'], // Web workers
     'object-src': ['none'], // Block plugins (Flash, Java, etc.)
     'base-uri': ['none'], // Prevent base tag hijacking
     'upgrade-insecure-requests': true, // Upgrade http to https
-    'report-to': null, // Report violations (e.g. `'/csp-violation-report'`)
-    'require-trusted-types-for': null,
-    'trusted-types': null,
-    sandbox: null,
-};
-/**
- * Sources that meet this trust requirement are included for it by default.
- * If null, no trusted sources are added to the directive automatically.
- * Directives that don't support sources or default to `['none']` are null.
- *
- * Feedback is welcome, please see the issues - https://github.com/fuzdev/fuz_ui/issues
- */
-export const csp_directive_required_trust_defaults = {
-    'default-src': null,
-    'script-src': 'high',
-    'script-src-elem': 'high',
-    'script-src-attr': null,
-    'style-src': 'medium',
-    'style-src-elem': 'medium',
-    'style-src-attr': 'medium',
-    'img-src': 'low',
-    'media-src': 'low',
-    'font-src': 'low',
-    'manifest-src': null,
-    'child-src': null,
-    'connect-src': 'medium',
-    'frame-src': 'medium',
-    'frame-ancestors': 'medium',
-    'form-action': 'medium',
-    'worker-src': 'medium',
-    'object-src': null,
-    'base-uri': null,
-    'upgrade-insecure-requests': null,
-    'report-to': null,
-    'require-trusted-types-for': null,
-    'trusted-types': null,
-    sandbox: null,
 };
 /**
  * Static data descriptors for the CSP directives.
  * Fuz excludes deprecated directives, so those are intentionally omitted,
  * but any newer missing directives are bugs.
  *
- * Could be co-located but is currently here to keep that module smaller.
- *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy}
  */
 export const csp_directive_specs = [

package/dist/csp_of_fuzdev.d.ts

@@ -1,6 +1,16 @@
-import type { CspSourceSpec } from './csp.ts';
+import type { CspDirectives } from './csp.ts';
 /**
- * Trusted sources owned by fuz.dev.
+ * Per-directive sources that allow full interop between fuzdev/sister sites
+ * (`*.fuz.dev`, `*.zzz.software`) — loading assets and APIs from each other,
+ * and iframing in both directions.
+ *
+ * Pass into `create_csp_directives({extend: [csp_directives_of_fuzdev]})`.
+ * Intended for sites within the ecosystem; external apps usually want a
+ * narrower, hand-written allow-list.
+ *
+ * Deliberately scoped — `script-src`, `style-src`, `worker-src`, etc. are not
+ * granted, even between sister sites. Add at the call site if a specific page
+ * needs them.
  */
-export declare const csp_trusted_sources_of_fuzdev: Array<CspSourceSpec>;
+export declare const csp_directives_of_fuzdev: Partial<CspDirectives>;
 //# sourceMappingURL=csp_of_fuzdev.d.ts.map

package/dist/csp_of_fuzdev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csp_of_fuzdev.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/csp_of_fuzdev.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,6BAA6B,EAAE,KAAK,CAAC,aAAa,CAK9D,CAAC"}
+{"version":3,"file":"csp_of_fuzdev.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/csp_of_fuzdev.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,EAAE,OAAO,CAAC,aAAa,CAW3D,CAAC"}