csprefabricate 0.2.3 → 0.3.1

package/README.md

@@ -14,20 +14,106 @@ Currently `csprefabricate`:
 
 - Validates directive names
 - Supports providing a list of TLDs for a given domain name
+- Provides warnings for insecure or incomplete CSP configurations, with options to disable specific warnings
+
+## Common CSP Issues
+
+By default, `csprefabricate` will warn you about common CSP issues, such as:
+
+- Overly permissive sources (e.g. using `*`)
+- Missing recommended directives (i.e. `object-src`, `base-uri`, `form-action`)
+- Use of `'unsafe-inline'` in `script-src`, even if nonces or hashes are present
+- Missing nonces or hashes when using `'unsafe-inline'` in `script-src`
+- Allowing `data:` in `img-src` or `media-src`
+
+You can control which warnings are shown by passing an optional `WarningOptions` object to the `create` function:
+
+```typescript
+import {
+    create,
+    Directive,
+    ContentSecurityPolicy,
+    WarningOptions,
+} from "csprefabricate";
+
+const csp: ContentSecurityPolicy = {
+    [Directive.SCRIPT_SRC]: ["*"],
+    [Directive.IMG_SRC]: ["data:"],
+};
+
+// Disable all warnings
+const warningOptions: WarningOptions = {
+    overlyPermissive: false,
+    missingDirectives: false,
+    unsafeInline: false,
+    missingNonceOrHash: false,
+    dataUri: false,
+};
+
+create(csp, warningOptions);
+```
+
+You can selectively enable or disable specific warnings as needed.
+
+## Real World Examples
+
+### Example 1: Basic Strict Policy
 
 ```typescript
-import {create} from "csprefabricate";
+import {create, Directive, ContentSecurityPolicy} from "csprefabricate";
 
-const input = {
+const csp: ContentSecurityPolicy = {
+    [Directive.DEFAULT_SRC]: ["'self'"],
+    [Directive.SCRIPT_SRC]: ["'self'"],
+    [Directive.STYLE_SRC]: ["'self'"],
+    [Directive.IMG_SRC]: ["'self'"],
+    [Directive.OBJECT_SRC]: ["'none'"],
+    [Directive.BASE_URI]: ["'self'"],
+    [Directive.FORM_ACTION]: ["'self'"],
+};
+
+const cspString = create(csp);
+// "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self';"
+```
+
+### Example 2: Allowing Google Analytics
+
+```typescript
+import {create, Directive, ContentSecurityPolicy} from "csprefabricate";
+
+const csp: ContentSecurityPolicy = {
     [Directive.DEFAULT_SRC]: ["self"],
-    [Directive.IMG_SRC]: ["self", {"*.google": [".com", ".com.au"]}],
-} satisfies ContentSecurityPolicy;
+    [Directive.SCRIPT_SRC]: ["self", "*.googletagmanager.com"],
+    [Directive.IMG_SRC]: [
+        "self",
+        "*.google-analytics.com",
+        "https://*.googletagmanager.com",
+    ],
+    [Directive.CONNECT_SRC]: [
+        "self",
+        "https://*.google-analytics.com",
+        "https://*.analytics.google.com",
+        "https://*.googletagmanager.com",
+    ],
+};
+
+const cspString = create(csp);
+// "default-src 'self'; script-src 'self' *.googletagmanager.com; img-src 'self' *.google-analytics.com https://*.googletagmanager.com; connect-src 'self' https://*.google-analytics.com https://*.analytics.google.com https://*.googletagmanager.com;"
+```
+
+### Example 3: Using TLD Expansion for Multiple Domains
+
+```typescript
+import {create, Directive, ContentSecurityPolicy} from "csprefabricate";
+
+const csp: ContentSecurityPolicy = {
+    [Directive.IMG_SRC]: ["self", {"*.example": [".com", ".co.uk", ".net"]}],
+};
 
-const output = create(csp);
-// > "default-src 'self'; img-src 'self' *.google.com *.google.com.au;",
+const cspString = create(csp);
+// "img-src 'self' *.example.com *.example.co.uk *.example.net;"
 ```
 
 ## Future
 
 - Generate baseline recommended CSPs (for example, Google Analytics)
-- Warnings for insecure configurations

package/dist/helpers.d.ts

@@ -1,2 +1,11 @@
+import { ContentSecurityPolicy } from "./types";
+export interface WarningOptions {
+    overlyPermissive?: boolean;
+    missingDirectives?: boolean;
+    unsafeInline?: boolean;
+    missingNonceOrHash?: boolean;
+    dataUri?: boolean;
+}
+export declare function warnOnCspIssues(csp: ContentSecurityPolicy, overrides?: WarningOptions): void;
 export declare const isValidDirective: (directive: string) => boolean;
 export declare const formatRule: (rule: string) => string;

package/dist/helpers.js

@@ -1,3 +1,11 @@
+import { Directive } from "./types";
+const DEFAULT_WARNINGS = {
+    overlyPermissive: true,
+    missingDirectives: true,
+    unsafeInline: true,
+    missingNonceOrHash: true,
+    dataUri: true,
+};
 const validDirectives = [
     "default-src",
     "script-src",
@@ -33,5 +41,53 @@ const specialRules = [
     "strict-dynamic",
     "unsafe-hashes",
 ];
+export function warnOnCspIssues(csp, overrides = {}) {
+    const options = { ...DEFAULT_WARNINGS, ...overrides };
+    // 1. Overly permissive: * in script-src, style-src, etc.
+    if (options.overlyPermissive) {
+        [Directive.SCRIPT_SRC, Directive.STYLE_SRC, Directive.IMG_SRC, Directive.CONNECT_SRC].forEach(directive => {
+            const rules = csp[directive];
+            if (Array.isArray(rules) && rules.includes("*")) {
+                console.warn(`[CSPrefabricate] Overly permissive: '*' found in ${directive}`);
+            }
+        });
+    }
+    // 2. Missing important directives
+    if (options.missingDirectives) {
+        [Directive.OBJECT_SRC, Directive.BASE_URI, Directive.FORM_ACTION].forEach(directive => {
+            if (!(directive in csp)) {
+                console.warn(`[CSPrefabricate] Missing recommended directive: ${directive}`);
+            }
+        });
+    }
+    // 3. Unsafe inline
+    if (options.unsafeInline) {
+        [Directive.SCRIPT_SRC, Directive.STYLE_SRC].forEach(directive => {
+            const rules = csp[directive];
+            if (Array.isArray(rules) && rules.includes("'unsafe-inline'")) {
+                console.warn(`[CSPrefabricate] 'unsafe-inline' found in ${directive}`);
+            }
+        });
+    }
+    // 4. Missing nonce or hash in script-src if 'unsafe-inline' is present
+    if (options.missingNonceOrHash) {
+        const rules = csp[Directive.SCRIPT_SRC];
+        if (Array.isArray(rules) && rules.includes("'unsafe-inline'")) {
+            const hasNonceOrHash = rules.some((r) => typeof r === "string" && (r.startsWith("'nonce-") || r.startsWith("'sha")));
+            if (!hasNonceOrHash) {
+                console.warn(`[CSPrefabricate] 'unsafe-inline' in script-src without nonce or hash`);
+            }
+        }
+    }
+    // 5. Permitting data: in img-src or media-src
+    if (options.dataUri) {
+        [Directive.IMG_SRC, Directive.MEDIA_SRC].forEach(directive => {
+            const rules = csp[directive];
+            if (Array.isArray(rules) && rules.includes("data:")) {
+                console.warn(`[CSPrefabricate] 'data:' allowed in ${directive}`);
+            }
+        });
+    }
+}
 export const isValidDirective = (directive) => validDirectives.includes(directive);
 export const formatRule = (rule) => specialRules.includes(rule) ? `'${rule}'` : rule;

package/dist/test/helpers.test.js

@@ -1,23 +1,123 @@
-import { describe, it } from "node:test";
+import { describe, it, beforeEach, after } from "node:test";
 import assert from "node:assert";
-import { formatRule, isValidDirective } from "../helpers";
+import { formatRule, isValidDirective, warnOnCspIssues } from "../helpers";
 import { Directive } from "../types";
-describe("Helpers tests", () => {
-    describe("isValidDirective", () => {
-        it("Returns true if directive is valid", () => {
+void describe("Helpers tests", () => {
+    void describe("isValidDirective", () => {
+        void it("Returns true if directive is valid", () => {
             assert.strictEqual(isValidDirective(Directive.BASE_URI), true);
             assert.strictEqual(isValidDirective("default-src"), true);
         });
-        it("Returns false if directive is invalid", () => {
+        void it("Returns false if directive is invalid", () => {
             assert.strictEqual(isValidDirective("some-src"), false);
         });
     });
-    describe("formatRule", () => {
-        it("Formats special rules with single quotes", () => {
+    void describe("formatRule", () => {
+        void it("Formats special rules with single quotes", () => {
             assert.strictEqual(formatRule("self"), `'self'`);
         });
-        it("Returns non-special rules", () => {
+        void it("Returns non-special rules", () => {
             assert.strictEqual(formatRule("google.com"), `google.com`);
         });
     });
+    void describe("warnOnCspIssues", () => {
+        let warnings = [];
+        const originalWarn = console.warn;
+        void beforeEach(() => {
+            warnings = [];
+            console.warn = (msg) => { warnings.push(msg); };
+        });
+        void after(() => {
+            console.warn = originalWarn;
+        });
+        void it("Warns on overly permissive *", () => {
+            const csp = {
+                [Directive.SCRIPT_SRC]: ["*"]
+            };
+            warnOnCspIssues(csp);
+            assert(warnings.some(w => w.includes("Overly permissive")));
+        });
+        void it("Warns on missing important directives", () => {
+            const csp = {
+                [Directive.DEFAULT_SRC]: ["'self'"]
+            };
+            warnOnCspIssues(csp);
+            assert(warnings.some(w => w.includes("Missing recommended directive: object-src")));
+            assert(warnings.some(w => w.includes("Missing recommended directive: base-uri")));
+            assert(warnings.some(w => w.includes("Missing recommended directive: form-action")));
+        });
+        void it("Warns on 'unsafe-inline' in script-src", () => {
+            const csp = {
+                [Directive.SCRIPT_SRC]: ["'unsafe-inline'"]
+            };
+            warnOnCspIssues(csp);
+            assert(warnings.some(w => w.includes("'unsafe-inline' found in script-src")));
+        });
+        void it("Warns on 'unsafe-inline' in script-src without nonce or hash", () => {
+            const csp = {
+                [Directive.SCRIPT_SRC]: ["'unsafe-inline'"]
+            };
+            warnOnCspIssues(csp);
+            assert(warnings.some(w => w.includes("'unsafe-inline' in script-src without nonce or hash")));
+        });
+        void it("Does not warn if nonce is present with 'unsafe-inline'", () => {
+            const csp = {
+                [Directive.SCRIPT_SRC]: ["'unsafe-inline'", "'nonce-abc'"]
+            };
+            warnOnCspIssues(csp);
+            assert(!warnings.some(w => w.includes("without nonce or hash")));
+        });
+        void it("Does not warn if hash is present with 'unsafe-inline'", () => {
+            const csp = {
+                [Directive.SCRIPT_SRC]: ["'unsafe-inline'", "'sha256-xyz'"]
+            };
+            warnOnCspIssues(csp);
+            assert(!warnings.some(w => w.includes("without nonce or hash")));
+        });
+        void it("Warns on data: in img-src", () => {
+            const csp = {
+                [Directive.IMG_SRC]: ["data:"]
+            };
+            warnOnCspIssues(csp);
+            assert(warnings.some(w => w.includes("'data:' allowed in img-src")));
+        });
+        void it("Respects warning options to opt out of specific warnings", () => {
+            const csp = {
+                [Directive.SCRIPT_SRC]: ["*"]
+            };
+            const opts = { overlyPermissive: false };
+            warnOnCspIssues(csp, opts);
+            assert(!warnings.some(w => w.includes("Overly permissive")));
+        });
+        void it("Does not warn if all warnings are disabled", () => {
+            const csp = {
+                [Directive.SCRIPT_SRC]: ["*"],
+                [Directive.IMG_SRC]: ["data:"]
+            };
+            const opts = {
+                overlyPermissive: false,
+                missingDirectives: false,
+                unsafeInline: false,
+                missingNonceOrHash: false,
+                dataUri: false
+            };
+            warnOnCspIssues(csp, opts);
+            assert.strictEqual(warnings.length, 0);
+        });
+        void it("Warns only for enabled warnings", () => {
+            const csp = {
+                [Directive.SCRIPT_SRC]: ["*", "'unsafe-inline'"],
+                [Directive.IMG_SRC]: ["data:"]
+            };
+            const opts = {
+                overlyPermissive: false,
+                missingDirectives: false,
+                unsafeInline: true
+            };
+            warnOnCspIssues(csp, opts);
+            assert(warnings.some(w => w.includes("'unsafe-inline' found in script-src")));
+            assert(!warnings.some(w => w.includes("Overly permissive")));
+            assert(!warnings.some(w => w.includes("Missing recommended directive")));
+        });
+    });
 });

package/dist/test/utils.test.js

@@ -1,20 +1,28 @@
-import { describe, it } from "node:test";
+import { describe, it, afterEach, mock, beforeEach } from "node:test";
 import assert from "node:assert";
 import { create, processRules } from "../utils";
 import { Directive } from "../types";
-describe("Utils tests", () => {
-    describe("processRules", () => {
-        it("Processes rules provided as an array of strings (simple)", () => {
+void describe("Utils tests", () => {
+    let mockWarn;
+    const originalWarn = console.warn;
+    void beforeEach(() => {
+        mockWarn = mock.method(console, "warn", () => { });
+    });
+    void afterEach(() => {
+        console.warn = originalWarn;
+    });
+    void describe("processRules", () => {
+        void it("Processes rules provided as an array of strings (simple)", () => {
             const rules = ["self", "*.google.com", "*.google.com.au"];
             assert.strictEqual(processRules(rules), `'self' *.google.com *.google.com.au`);
         });
-        it("Processes rules provided a complex list of tlds", () => {
+        void it("Processes rules provided a complex list of tlds", () => {
             const rules = ["self", { "*.google": [".com", ".com.au"] }];
             assert.strictEqual(processRules(rules), `'self' *.google.com *.google.com.au`);
         });
     });
-    describe("create", () => {
-        it("Formats a CSP string with all rules", () => {
+    void describe("create", () => {
+        void it("Formats a CSP string with all rules", () => {
             const csp = {
                 [Directive.DEFAULT_SRC]: ["self"],
                 [Directive.SCRIPT_SRC]: ["self", "js.example.com"],
@@ -48,14 +56,7 @@ describe("Utils tests", () => {
             const cspString = create(csp);
             assert.strictEqual(cspString, "default-src 'self'; script-src 'self' js.example.com; style-src 'self' css.example.com; img-src 'self' *.google.com *.google.com.au; connect-src 'self'; font-src 'self' font.example.com; object-src 'none'; media-src 'self' media.example.com; frame-src 'self'; sandbox allow-scripts; report-uri /my-report-uri; child-src 'self'; form-action 'self'; frame-ancestors 'none'; plugin-types application/pdf; base-uri 'self'; report-to myGroupName; worker-src 'none'; manifest-src 'none'; prefetch-src 'none'; navigate-to example.com; require-trusted-types-for script; trusted-types 'none'; upgrade-insecure-requests; block-all-mixed-content;");
         });
-        it("Handles blank directives", () => {
-            const csp = {
-                [Directive.SANDBOX]: [],
-            };
-            const cspString = create(csp);
-            assert.strictEqual(cspString, "sandbox;");
-        });
-        it("Ignores invalid directives", () => {
+        void it("Ignores invalid directives", () => {
             const csp = {
                 [Directive.DEFAULT_SRC]: ["self"],
                 // @ts-expect-error deliberate testing of invalid directive
@@ -65,5 +66,43 @@ describe("Utils tests", () => {
             const cspString = create(csp);
             assert.strictEqual(cspString, "default-src 'self'; img-src my.domain.com;");
         });
+        void it("Calls warning helper when invoked", () => {
+            const csp = {
+                [Directive.DEFAULT_SRC]: ["self"],
+            };
+            create(csp);
+            assert.equal(mockWarn.mock.calls.length, 3);
+            const args = mockWarn.mock.calls.map((call) => call.arguments);
+            assert.equal(args[0][0], "[CSPrefabricate] Missing recommended directive: object-src");
+            assert.equal(args[1][0], "[CSPrefabricate] Missing recommended directive: base-uri");
+            assert.equal(args[2][0], "[CSPrefabricate] Missing recommended directive: form-action");
+        });
+    });
+    void describe("Edge cases", () => {
+        void it("Handles empty rules array", () => {
+            const csp = {
+                [Directive.DEFAULT_SRC]: [],
+            };
+            const cspString = create(csp);
+            assert.strictEqual(cspString, "default-src;");
+        });
+        void it("Handles completely empty policy object", () => {
+            const csp = {};
+            const cspString = create(csp);
+            assert.strictEqual(cspString, "");
+        });
+        void it("Handles duplicate rules in an array", () => {
+            const csp = {
+                [Directive.DEFAULT_SRC]: ["self", "self", "example.com", "example.com"],
+            };
+            const cspString = create(csp);
+            assert.strictEqual(cspString, "default-src 'self' example.com;");
+        });
+        void it("Ignores non-string, non-object values in rules array at runtime", () => {
+            const csp = {
+                [Directive.DEFAULT_SRC]: ["self", 123, false, null, undefined],
+            };
+            assert.doesNotThrow(() => create(csp));
+        });
     });
 });

package/dist/types.d.ts

@@ -55,4 +55,4 @@ interface ContentSecurityPolicy {
     [Directive.UPGRADE_INSECURE_REQUESTS]?: BlankDirectiveRule;
     [Directive.BLOCK_ALL_MIXED_CONTENT]?: BlankDirectiveRule;
 }
-export { ContentSecurityPolicy, Rules, Directive };
+export { ContentSecurityPolicy, Rules, Directive, BasicDirectiveRule };

package/dist/utils.d.ts

@@ -1,3 +1,10 @@
-import { ContentSecurityPolicy } from "./types";
-export declare const processRules: (rules: Array<string> | Array<string | Record<string, Array<string>>>) => string;
-export declare const create: (obj: ContentSecurityPolicy) => string;
+import { WarningOptions } from "./helpers";
+import { ContentSecurityPolicy, BasicDirectiveRule } from "./types";
+export declare const processRules: (rules: BasicDirectiveRule) => string;
+/**
+ * Creates a CSP string from a ContentSecurityPolicy object.
+ * Filters out invalid directives and formats the CSP string.
+ * @param obj - The ContentSecurityPolicy object.
+ * @returns The formatted CSP string.
+ */
+export declare const create: (obj: ContentSecurityPolicy, warningOptions?: WarningOptions) => string;

package/dist/utils.js

@@ -1,26 +1,46 @@
-import { formatRule, isValidDirective } from "./helpers";
+import { formatRule, isValidDirective, warnOnCspIssues } from "./helpers";
 export const processRules = (rules) => {
-    return rules
-        .map((rule) => {
+    // Flatten and deduplicate rules
+    const seen = new Set();
+    for (const rule of rules) {
         if (typeof rule === "object") {
-            return Object.entries(rule).map(([domain, tlds]) => tlds.map((tld) => `${domain}${tld}`).join(" "));
+            for (const [domain, tlds] of Object.entries(rule)) {
+                for (const tld of tlds) {
+                    seen.add(`${domain}${tld}`);
+                }
+            }
         }
         else {
-            return formatRule(rule);
+            seen.add(formatRule(rule));
         }
-    })
-        .join(" ");
+    }
+    return Array.from(seen).join(" ");
 };
-export const create = (obj) => {
+/**
+ * Creates a CSP string from a ContentSecurityPolicy object.
+ * Filters out invalid directives and formats the CSP string.
+ * @param obj - The ContentSecurityPolicy object.
+ * @returns The formatted CSP string.
+ */
+export const create = (obj, warningOptions) => {
+    warnOnCspIssues(obj, warningOptions);
     const entries = Object.entries(obj);
     const cspString = entries
         .filter(([directive, _rules]) => {
         const isValid = isValidDirective(directive);
         if (!isValid) {
-            console.warn(`"${directive}" is not a valid CSP directive and has been ignored.`);
+            console.warn(`[CSPrefabricate] "${directive}" is not a valid CSP directive and has been ignored.`);
         }
         return isValid;
     })
-        .map(([directive, rules]) => `${directive}${rules && rules.length > 0 ? " " + processRules(rules) : ""}`);
-    return `${cspString.join("; ")};`;
+        .map(([directive, rules]) => {
+        if (Array.isArray(rules)) {
+            // Filter out non-string/object values at runtime
+            const filtered = rules.filter((r) => typeof r === "string" || (typeof r === "object" && r !== null));
+            const processed = processRules(filtered);
+            return processed ? `${directive} ${processed}` : `${directive}`;
+        }
+        return `${directive}`;
+    });
+    return cspString.length > 0 ? `${cspString.join("; ")};` : "";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "csprefabricate",
-    "version": "0.2.3",
+    "version": "0.3.1",
     "packageManager": "yarn@4.5.3",
     "type": "module",
     "devDependencies": {
@@ -24,7 +24,6 @@
         "prepack": "yarn typecheck && yarn test && yarn build",
         "prettier": "prettier . --write",
         "prepublish": "yarn version check",
-        "publish": "npm publish",
         "test": "tsx --test src/test/**/*test.ts",
         "typecheck": "tsc --noEmit",
         "lint": "eslint ."