csprefabricate 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 James Toohey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# csprefabricate (Work in progress)
+
+**Generate a valid CSP with JavaScript. Built with TypeScript.**
+
+Content Security Policies (CSPs) are cumbersome strings that are frusting to work with:
+
+- Fickle syntax
+- Duplicattion when multiple TLDs are required
+- Easy to allow insecure configuration
+
+This project aims to make creating useful and secure CSPs a more pleasant experience.
+
+Currently `csprefabricate`:
+
+- Validates directive names
+- Supports providing a list of TLDs for a given domain name
+
+```typescript
+import {create} from "csprefabricate";
+
+const input = {
+    [Directive.DEFAULT_SRC]: ["self"],
+    [Directive.IMG_SRC]: ["self", {"*.google": [".com", ".com.au"]}],
+} satisfies ContentSecurityPolicy;
+
+const output = create(csp);
+// > "default-src 'self'; img-src 'self' *.google.com *.google.com.au;",
+```
+
+## Future
+
+- Generate baseline recommended CSPs (for example, Google Analytics)
+- Warnings for insecure configurations

package/dist/helpers.d.ts

@@ -0,0 +1,2 @@
+export declare const isValidDirective: (directive: string) => boolean;
+export declare const formatRule: (rule: string) => string;

package/dist/helpers.js

@@ -0,0 +1,37 @@
+const validDirectives = [
+    "default-src",
+    "script-src",
+    "style-src",
+    "img-src",
+    "connect-src",
+    "font-src",
+    "object-src",
+    "media-src",
+    "frame-src",
+    "sandbox",
+    "report-uri",
+    "child-src",
+    "form-action",
+    "frame-ancestors",
+    "plugin-types",
+    "base-uri",
+    "report-to",
+    "worker-src",
+    "manifest-src",
+    "prefetch-src",
+    "navigate-to",
+    "require-trusted-types-for",
+    "trusted-types",
+    "upgrade-insecure-requests",
+    "block-all-mixed-content",
+];
+const specialRules = [
+    "none",
+    "self",
+    "unsafe-inline",
+    "unsafe-eval",
+    "strict-dynamic",
+    "unsafe-hashes",
+];
+export const isValidDirective = (directive) => validDirectives.includes(directive);
+export const formatRule = (rule) => specialRules.includes(rule) ? `'${rule}'` : rule;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type ContentSecurityPolicy, Directive } from "types";
+import { create } from "utils";
+export { create, type Directive, type ContentSecurityPolicy };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { Directive } from "types";
+import { create } from "utils";
+export { create };

package/dist/test/helpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/helpers.test.js

@@ -0,0 +1,23 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { formatRule, isValidDirective } from "../helpers";
+import { Directive } from "../types";
+describe("Helpers tests", () => {
+    describe("isValidDirective", () => {
+        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", () => {
+            assert.strictEqual(isValidDirective("some-src"), false);
+        });
+    });
+    describe("formatRule", () => {
+        it("Formats special rules with single quotes", () => {
+            assert.strictEqual(formatRule("self"), `'self'`);
+        });
+        it("Returns non-special rules", () => {
+            assert.strictEqual(formatRule("google.com"), `google.com`);
+        });
+    });
+});

package/dist/test/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/utils.test.js

@@ -0,0 +1,69 @@
+import { describe, it } 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)", () => {
+            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", () => {
+            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", () => {
+            const csp = {
+                [Directive.DEFAULT_SRC]: ["self"],
+                [Directive.SCRIPT_SRC]: ["self", "js.example.com"],
+                [Directive.STYLE_SRC]: ["self", "css.example.com"],
+                [Directive.IMG_SRC]: [
+                    "self",
+                    { "*.google": [".com", ".com.au"] },
+                ],
+                [Directive.CONNECT_SRC]: ["self"],
+                [Directive.FONT_SRC]: ["self", "font.example.com"],
+                [Directive.OBJECT_SRC]: ["none"],
+                [Directive.MEDIA_SRC]: ["self", "media.example.com"],
+                [Directive.FRAME_SRC]: ["self"],
+                [Directive.SANDBOX]: ["allow-scripts"],
+                [Directive.REPORT_URI]: ["/my-report-uri"],
+                [Directive.CHILD_SRC]: ["self"],
+                [Directive.FORM_ACTION]: ["self"],
+                [Directive.FRAME_ANCESTORS]: ["none"],
+                [Directive.PLUGIN_TYPES]: ["application/pdf"],
+                [Directive.BASE_URI]: ["self"],
+                [Directive.REPORT_TO]: ["myGroupName"],
+                [Directive.WORKER_SRC]: ["none"],
+                [Directive.MANIFEST_SRC]: ["none"],
+                [Directive.PREFETCH_SRC]: ["none"],
+                [Directive.NAVIGATE_TO]: ["example.com"],
+                [Directive.REQUIRE_TRUSTED_TYPES_FOR]: ["script"],
+                [Directive.TRUSTED_TYPES]: ["none"],
+                [Directive.UPGRADE_INSECURE_REQUESTS]: null,
+                [Directive.BLOCK_ALL_MIXED_CONTENT]: null,
+            };
+            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", () => {
+            const csp = {
+                [Directive.DEFAULT_SRC]: ["self"],
+                // @ts-expect-error deliberate testing of invalid directive
+                ["invalid-directive"]: ["self"],
+                [Directive.IMG_SRC]: ["my.domain.com"]
+            };
+            const cspString = create(csp);
+            assert.strictEqual(cspString, "default-src 'self'; img-src my.domain.com;");
+        });
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+declare enum Directive {
+    DEFAULT_SRC = "default-src",
+    SCRIPT_SRC = "script-src",
+    STYLE_SRC = "style-src",
+    IMG_SRC = "img-src",
+    CONNECT_SRC = "connect-src",
+    FONT_SRC = "font-src",
+    OBJECT_SRC = "object-src",
+    MEDIA_SRC = "media-src",
+    FRAME_SRC = "frame-src",
+    SANDBOX = "sandbox",
+    REPORT_URI = "report-uri",
+    CHILD_SRC = "child-src",
+    FORM_ACTION = "form-action",
+    FRAME_ANCESTORS = "frame-ancestors",
+    PLUGIN_TYPES = "plugin-types",
+    BASE_URI = "base-uri",
+    REPORT_TO = "report-to",
+    WORKER_SRC = "worker-src",
+    MANIFEST_SRC = "manifest-src",
+    PREFETCH_SRC = "prefetch-src",
+    NAVIGATE_TO = "navigate-to",
+    REQUIRE_TRUSTED_TYPES_FOR = "require-trusted-types-for",
+    TRUSTED_TYPES = "trusted-types",
+    UPGRADE_INSECURE_REQUESTS = "upgrade-insecure-requests",
+    BLOCK_ALL_MIXED_CONTENT = "block-all-mixed-content"
+}
+type BasicDirectiveRule = Array<string | Record<string, Array<string>>>;
+type BlankDirectiveRule = null;
+type Rules = BasicDirectiveRule | BlankDirectiveRule;
+interface ContentSecurityPolicy {
+    [Directive.DEFAULT_SRC]?: BasicDirectiveRule;
+    [Directive.SCRIPT_SRC]?: BasicDirectiveRule;
+    [Directive.STYLE_SRC]?: BasicDirectiveRule;
+    [Directive.IMG_SRC]?: BasicDirectiveRule;
+    [Directive.CONNECT_SRC]?: BasicDirectiveRule;
+    [Directive.FONT_SRC]?: BasicDirectiveRule;
+    [Directive.OBJECT_SRC]?: BasicDirectiveRule;
+    [Directive.MEDIA_SRC]?: BasicDirectiveRule;
+    [Directive.FRAME_SRC]?: BasicDirectiveRule;
+    [Directive.SANDBOX]?: BasicDirectiveRule;
+    [Directive.REPORT_URI]?: BasicDirectiveRule;
+    [Directive.CHILD_SRC]?: BasicDirectiveRule;
+    [Directive.FORM_ACTION]?: BasicDirectiveRule;
+    [Directive.FRAME_ANCESTORS]?: BasicDirectiveRule;
+    [Directive.PLUGIN_TYPES]?: BasicDirectiveRule;
+    [Directive.BASE_URI]?: BasicDirectiveRule;
+    [Directive.REPORT_TO]?: BasicDirectiveRule;
+    [Directive.WORKER_SRC]?: BasicDirectiveRule;
+    [Directive.MANIFEST_SRC]?: BasicDirectiveRule;
+    [Directive.PREFETCH_SRC]?: BasicDirectiveRule;
+    [Directive.NAVIGATE_TO]?: BasicDirectiveRule;
+    [Directive.REQUIRE_TRUSTED_TYPES_FOR]?: BasicDirectiveRule;
+    [Directive.TRUSTED_TYPES]?: BasicDirectiveRule;
+    [Directive.UPGRADE_INSECURE_REQUESTS]?: BlankDirectiveRule;
+    [Directive.BLOCK_ALL_MIXED_CONTENT]?: BlankDirectiveRule;
+}
+export { type ContentSecurityPolicy, type Rules, Directive };

package/dist/types.js

@@ -0,0 +1,29 @@
+var Directive;
+(function (Directive) {
+    Directive["DEFAULT_SRC"] = "default-src";
+    Directive["SCRIPT_SRC"] = "script-src";
+    Directive["STYLE_SRC"] = "style-src";
+    Directive["IMG_SRC"] = "img-src";
+    Directive["CONNECT_SRC"] = "connect-src";
+    Directive["FONT_SRC"] = "font-src";
+    Directive["OBJECT_SRC"] = "object-src";
+    Directive["MEDIA_SRC"] = "media-src";
+    Directive["FRAME_SRC"] = "frame-src";
+    Directive["SANDBOX"] = "sandbox";
+    Directive["REPORT_URI"] = "report-uri";
+    Directive["CHILD_SRC"] = "child-src";
+    Directive["FORM_ACTION"] = "form-action";
+    Directive["FRAME_ANCESTORS"] = "frame-ancestors";
+    Directive["PLUGIN_TYPES"] = "plugin-types";
+    Directive["BASE_URI"] = "base-uri";
+    Directive["REPORT_TO"] = "report-to";
+    Directive["WORKER_SRC"] = "worker-src";
+    Directive["MANIFEST_SRC"] = "manifest-src";
+    Directive["PREFETCH_SRC"] = "prefetch-src";
+    Directive["NAVIGATE_TO"] = "navigate-to";
+    Directive["REQUIRE_TRUSTED_TYPES_FOR"] = "require-trusted-types-for";
+    Directive["TRUSTED_TYPES"] = "trusted-types";
+    Directive["UPGRADE_INSECURE_REQUESTS"] = "upgrade-insecure-requests";
+    Directive["BLOCK_ALL_MIXED_CONTENT"] = "block-all-mixed-content";
+})(Directive || (Directive = {}));
+export { Directive };

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+import { type ContentSecurityPolicy } from "types";
+export declare const processRules: (rules: Array<string> | Array<string | Record<string, Array<string>>>) => string;
+export declare const create: (obj: ContentSecurityPolicy) => string;

package/dist/utils.js

@@ -0,0 +1,27 @@
+import { formatRule, isValidDirective } from "helpers";
+import { Directive } from "types";
+export const processRules = (rules) => {
+    return rules
+        .map((rule) => {
+        if (typeof rule === "object") {
+            return Object.entries(rule).map(([domain, tlds]) => tlds.map((tld) => `${domain}${tld}`).join(" "));
+        }
+        else {
+            return formatRule(rule);
+        }
+    })
+        .join(" ");
+};
+export const create = (obj) => {
+    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.`);
+        }
+        return isValid;
+    })
+        .map(([directive, rules]) => `${directive}${rules && rules.length > 0 ? " " + processRules(rules) : ""}`);
+    return `${cspString.join("; ")};`;
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "csprefabricate",
+    "version": "0.2.0",
+    "packageManager": "yarn@4.5.3",
+    "type": "module",
+    "devDependencies": {
+        "@tsconfig/node-lts": "^22.0.1",
+        "@types/node": "^22.13.5",
+        "prettier": "^3.5.2",
+        "tsx": "^4.19.3",
+        "typescript": "^5.7.3"
+    },
+    "main": "dist/index.js",
+    "files": [
+        "dist/"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "pack": "npm pack",
+        "prepack": "yarn typecheck && yarn test && yarn build",
+        "prettier": "prettier . --write",
+        "prepublish": "yarn version check",
+        "publish": "yarn npm publish",
+        "test": "tsx --test src/test/**/*test.ts",
+        "typecheck": "tsc --noEmit"
+    }
+}