@cronn/playwright-utils 0.8.0 → 0.9.0

package/dist/index.d.mts

@@ -591,6 +591,33 @@ export declare class RouteInterceptorFixture {
   intercept(filter: RouteFilter): RouteInterceptor;
 }
 //#endregion
+//#region src/security/csp-report.d.ts
+/**
+ * Returns the `Content-Security-Policy` header of a response, or an empty
+ * string if the response or the header is missing.
+ */
+export declare function getCspHeader(response: Response | null): Promise<string>;
+/**
+ * Evaluates a `Content-Security-Policy` header against a set of recommended
+ * directives and returns the result as a Markdown report.
+ *
+ * The report lists all directives of the header, followed by recommendations
+ * for missing or weak directives. Missing fetch directives are evaluated using
+ * `default-src`, just like the browser falls back to it. Nonces are masked as
+ * `[NONCE_0]`, `[NONCE_1]`, … to keep the report deterministic for file snapshots.
+ *
+ * @example
+ * ```ts
+ * const response = await page.goto("/");
+ * const cspHeader = await getCspHeader(response);
+ *
+ * expect(cspReport(cspHeader)).toMatchTextFile({
+ *   fileExtension: "md",
+ * });
+ * ```
+ */
+export declare function cspReport(header: string): string;
+//#endregion
 //#region src/file.d.ts
 /**
  * Resolves the given path segments against the root directory of the closest

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { expect } from "@playwright/test";
+import { markdownTable } from "markdown-table";
 import path from "node:path";
 import { packageDirectorySync } from "package-directory";
 import { maskString, stringNormalizer } from "@cronn/playwright-file-snapshots";
@@ -770,6 +771,225 @@ function modifyTextBody(modifier) {
 	});
 }
 //#endregion
+//#region src/normalizers/masked-value.ts
+/**
+* Formats a name as a masked placeholder, e.g. `maskedValue("base url")`
+* returns `[BASE_URL]`.
+*
+* @param name - Name of the masked value
+*/
+function maskedValue(name) {
+	return `[${name.toUpperCase().replace(/[ -.:,;]/g, "_")}]`;
+}
+/**
+* Creates a factory for indexed masked placeholders, e.g. `[USER_1]`.
+*
+* @param name - Name of the masked value
+* @returns A function mapping an index to a masked placeholder
+*/
+function maskedValueWithIndex(name) {
+	return (index) => maskedValue(`${name}_${index}`);
+}
+//#endregion
+//#region src/security/csp-report.ts
+const RECOMMENDED_DIRECTIVES = [
+	{ name: "upgrade-insecure-requests" },
+	{ name: "trusted-types" },
+	{
+		name: "require-trusted-types-for",
+		values: ["'script'"]
+	},
+	{
+		name: "default-src",
+		values: ["'self'"]
+	},
+	{
+		name: "script-src",
+		requireNonce: true,
+		tolerated: ["'strict-dynamic'"],
+		fallback: "default-src",
+		optional: ["script-src-elem", "script-src-attr"]
+	},
+	{
+		name: "script-src-elem",
+		requireNonce: true,
+		tolerated: ["'strict-dynamic'"],
+		optional: true
+	},
+	{
+		name: "script-src-attr",
+		values: ["'none'"],
+		optional: true
+	},
+	{
+		name: "style-src",
+		requireNonce: true,
+		fallback: "default-src",
+		optional: ["style-src-elem", "style-src-attr"]
+	},
+	{
+		name: "style-src-elem",
+		requireNonce: true,
+		optional: true
+	},
+	{
+		name: "style-src-attr",
+		values: ["'none'"],
+		optional: true
+	},
+	{
+		name: "img-src",
+		values: ["'self'", "data:"],
+		fallback: "default-src"
+	},
+	{
+		name: "font-src",
+		values: ["'self'"],
+		fallback: "default-src"
+	},
+	{
+		name: "connect-src",
+		values: ["'self'"],
+		fallback: "default-src"
+	},
+	{
+		name: "object-src",
+		values: ["'none'"]
+	},
+	{
+		name: "base-uri",
+		values: ["'self'"]
+	},
+	{
+		name: "form-action",
+		values: ["'self'"]
+	},
+	{
+		name: "frame-ancestors",
+		values: ["'none'"]
+	}
+];
+const NONCE_PLACEHOLDER = "'nonce-[RANDOM]'";
+const MASKED_NONCE = maskedValueWithIndex("NONCE");
+/**
+* Returns the `Content-Security-Policy` header of a response, or an empty
+* string if the response or the header is missing.
+*/
+async function getCspHeader(response) {
+	return await response?.headerValue("content-security-policy") ?? "";
+}
+/**
+* Evaluates a `Content-Security-Policy` header against a set of recommended
+* directives and returns the result as a Markdown report.
+*
+* The report lists all directives of the header, followed by recommendations
+* for missing or weak directives. Missing fetch directives are evaluated using
+* `default-src`, just like the browser falls back to it. Nonces are masked as
+* `[NONCE_0]`, `[NONCE_1]`, … to keep the report deterministic for file snapshots.
+*
+* @example
+* ```ts
+* const response = await page.goto("/");
+* const cspHeader = await getCspHeader(response);
+*
+* expect(cspReport(cspHeader)).toMatchTextFile({
+*   fileExtension: "md",
+* });
+* ```
+*/
+function cspReport(header) {
+	const { directives, recommendations } = evaluateCsp(parseCsp(header));
+	return [
+		"# CSP Report",
+		"## Detected Directives",
+		directives.length === 0 ? "None" : markdownTable([["Directive", "Value"], ...maskNonces(directives).map((directive) => [code(directive.name), formatValues(directive.values)])]),
+		"## Recommendations",
+		recommendations.length === 0 ? "None" : recommendations.map((recommendation) => `- ${code(recommendation.directive)}: ${recommendation.message}`).join("\n")
+	].join("\n\n").concat("\n");
+}
+function parseCsp(header) {
+	return header.split(";").map((directive) => directive.trim()).filter((directive) => directive !== "").map((directive) => {
+		const [name = "", ...values] = directive.split(/\s+/);
+		return {
+			name: name.toLowerCase(),
+			values
+		};
+	});
+}
+function evaluateCsp(directives) {
+	const directivesByName = /* @__PURE__ */ new Map();
+	for (const directive of directives) if (!directivesByName.has(directive.name)) directivesByName.set(directive.name, directive);
+	return {
+		directives,
+		recommendations: RECOMMENDED_DIRECTIVES.flatMap((recommended) => evaluateDirective(recommended, directivesByName).map((message) => ({
+			directive: recommended.name,
+			message
+		})))
+	};
+}
+function evaluateDirective(recommended, directivesByName) {
+	const directive = directivesByName.get(recommended.name);
+	if (directive === void 0 && isOptional(recommended, directivesByName)) return [];
+	const fallback = recommended.fallback !== void 0 ? directivesByName.get(recommended.fallback) : void 0;
+	const actual = directive ?? fallback;
+	if (actual === void 0) return [`Missing, add ${code([recommended.name, ...formatRecommendedValues(recommended)].join(" "))}`];
+	const inherited = directive === void 0 ? ` (inherited from ${code(actual.name)})` : "";
+	const messages = [];
+	const recommendedValues = recommended.values;
+	const extraValues = findExtraValues(recommended, actual.values);
+	const hasRecommendedValue = extraValues.length < actual.values.length;
+	if (recommendedValues !== void 0 && extraValues.length > 0 && !hasRecommendedValue) messages.push(`Add ${formatValues(recommendedValues)}`);
+	if (recommended.requireNonce === true && !actual.values.some(isNonce)) messages.push(`Add a nonce source`);
+	for (const value of extraValues) messages.push(`Remove ${code(value)}${inherited}`);
+	return messages;
+}
+function isOptional(recommended, directivesByName) {
+	if (Array.isArray(recommended.optional)) return recommended.optional.every((name) => directivesByName.has(name));
+	return recommended.optional === true;
+}
+/**
+* Returns all sources which are neither recommended nor tolerated. Directives
+* without recommended sources accept any value, and `'none'` is always
+* accepted as it is stricter than any recommendation.
+*/
+function findExtraValues(recommended, values) {
+	if (recommended.values === void 0 && recommended.requireNonce !== true || isNone(values)) return [];
+	const acceptedValues = [...recommended.values ?? [], ...recommended.tolerated ?? []];
+	return values.filter((value) => !acceptedValues.includes(value) && !(recommended.requireNonce === true && isNonce(value)));
+}
+function formatRecommendedValues(recommended) {
+	return [...recommended.requireNonce === true ? [NONCE_PLACEHOLDER] : [], ...recommended.values ?? []];
+}
+function maskNonces(directives) {
+	const nonceIndices = /* @__PURE__ */ new Map();
+	function maskNonce(value) {
+		if (!isNonce(value)) return value;
+		let index = nonceIndices.get(value);
+		if (index === void 0) {
+			index = nonceIndices.size;
+			nonceIndices.set(value, index);
+		}
+		return `'nonce-${MASKED_NONCE(index)}'`;
+	}
+	return directives.map((directive) => ({
+		...directive,
+		values: directive.values.map(maskNonce)
+	}));
+}
+function isNone(values) {
+	return values.length === 1 && values[0] === "'none'";
+}
+function isNonce(value) {
+	return value.startsWith("'nonce-");
+}
+function formatValues(values) {
+	if (values.length === 0) return "_none_";
+	return code(values.join(" "));
+}
+function code(text) {
+	return `\`${text.replaceAll("|", "\\|")}\``;
+}
+//#endregion
 //#region src/file.ts
 /**
 * Resolves the given path segments against the root directory of the closest
@@ -990,26 +1210,6 @@ function roleLocators(locator, defaultOptions = DEFAULT_OPTIONS) {
 	return Object.fromEntries(ROLES.map((role) => [role, getByRole(role)]));
 }
 //#endregion
-//#region src/normalizers/masked-value.ts
-/**
-* Formats a name as a masked placeholder, e.g. `maskedValue("base url")`
-* returns `[BASE_URL]`.
-*
-* @param name - Name of the masked value
-*/
-function maskedValue(name) {
-	return `[${name.toUpperCase().replace(/[ -.:,;]/g, "_")}]`;
-}
-/**
-* Creates a factory for indexed masked placeholders, e.g. `[USER_1]`.
-*
-* @param name - Name of the masked value
-* @returns A function mapping an index to a masked placeholder
-*/
-function maskedValueWithIndex(name) {
-	return (index) => maskedValue(`${name}_${index}`);
-}
-//#endregion
 //#region src/normalizers/mask-base-url.ts
 /**
 * Creates a normalizer that replaces occurrences of the base URL with
@@ -1025,4 +1225,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { ConsoleCaptor, CspCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, captureCspViolations, createFetchAdapter, cspFixtures, extendLocator, formFiller, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, roleLocators };
+export { ConsoleCaptor, CspCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, captureCspViolations, createFetchAdapter, cspFixtures, cspReport, extendLocator, formFiller, getCspHeader, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, roleLocators };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/playwright-utils",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",
@@ -29,33 +29,34 @@
     }
   },
   "dependencies": {
+    "markdown-table": "^3.0.4",
     "package-directory": "^8.2.0"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
     "@changesets/cli": "3.0.3",
-    "@cronn/element-snapshot": "0.30.0",
+    "@cronn/element-snapshot": "0.32.1",
     "@cronn/playwright-file-snapshots": "2.2.2",
     "@playwright/test": "1.63.0",
-    "@types/node": "24.19.0",
+    "@types/node": "24.19.1",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "5.0.2",
-    "eslint": "10.11.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "eslint": "10.12.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.2",
     "eslint-plugin-unused-imports": "4.4.1",
-    "knip": "6.38.0",
-    "oxc-minify": "0.151.0",
-    "oxfmt": "0.70.0",
-    "publint": "0.3.24",
+    "knip": "6.39.0",
+    "oxc-minify": "0.153.0",
+    "oxfmt": "0.72.0",
+    "publint": "0.3.25",
     "rimraf": "6.1.3",
     "tsdown": "0.23.0",
-    "turbo": "2.11.5",
+    "turbo": "2.11.7",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "8.70.1",
+    "typescript-eslint": "8.71.1",
     "vitepress": "2.0.0-alpha.20",
     "vitepress-plugin-group-icons": "1.7.6",
-    "vitest": "5.0.2"
+    "vitest": "5.0.3"
   },
   "peerDependencies": {
     "@cronn/playwright-file-snapshots": "^2",
@@ -64,7 +65,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "12.9.1",
+      "version": "12.11.2",
       "onFail": "download"
     },
     "runtime": {