@cronn/playwright-utils 0.8.0 → 0.10.0

package/dist/index.d.mts

@@ -591,6 +591,65 @@ 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/security/response-header-report.d.ts
+type ResponseHeaderType = "document" | "api";
+interface ResponseHeaderReportOptions {
+  type: ResponseHeaderType;
+}
+/**
+ * Returns all headers of a response, or an empty object if the response is
+ * missing. For page responses, this uses `response.allHeaders()`, which in
+ * contrast to `response.headers()` includes security-related headers.
+ */
+export declare function getResponseHeaders(response: Response | APIResponse | null): Promise<Record<string, string>>;
+/**
+ * Evaluates the headers of a response against a set of recommended security
+ * headers and returns the result as a Markdown report.
+ *
+ * The report lists all evaluated headers of the response, followed by
+ * recommendations for missing or deviating headers and for discouraged headers
+ * to remove. Unrelated headers like `date` are omitted to keep the report
+ * deterministic for file snapshots.
+ *
+ * @example
+ * ```ts
+ * const response = await page.goto("/");
+ * const headers = await getResponseHeaders(response);
+ *
+ * expect(responseHeaderReport(headers, { type: "document" })).toMatchTextFile({
+ *   fileExtension: "md",
+ * });
+ * ```
+ */
+export declare function responseHeaderReport(headers: Record<string, string>, options: ResponseHeaderReportOptions): string;
+//#endregion
 //#region src/file.d.ts
 /**
  * Resolves the given path segments against the root directory of the closest
@@ -730,4 +789,4 @@ export declare function maskedValueWithIndex(name: string): (index: number) => s
  */
 type PlaywrightTarget = Page | Locator;
 //#endregion
-export type { ConsoleMessageFilter, ConsoleMessageLevel, CspFixtures, CspViolation, ExtendedLocator, FormFields, HttpMethod, PlaywrightTarget, ResponseHandler, RoleLocators, RouteFilter };
+export type { ConsoleMessageFilter, ConsoleMessageLevel, CspFixtures, CspViolation, ExtendedLocator, FormFields, HttpMethod, PlaywrightTarget, ResponseHandler, ResponseHeaderReportOptions, ResponseHeaderType, RoleLocators, RouteFilter };

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,420 @@ 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/utils/markdown.ts
+const NONE = "None";
+/**
+* Creates a Markdown document with a top-level title and a second-level
+* heading for each section.
+*/
+function markdownDocument(title, sections) {
+	return [`# ${title}`, ...sections.flatMap((section) => [`## ${section.heading}`, section.content])].join("\n\n").concat("\n");
+}
+/**
+* Creates a Markdown table, or `None` if there are no rows.
+*/
+function markdownTableOrNone(header, rows) {
+	return rows.length === 0 ? NONE : markdownTable([header, ...rows]);
+}
+/**
+* Creates a Markdown list with an item per entry formatted as
+* `` `name`: message ``, or `None` if there are no entries.
+*/
+function markdownEntriesOrNone(entries) {
+	return entries.length === 0 ? NONE : entries.map((entry) => `- ${code(entry.name)}: ${entry.message}`).join("\n");
+}
+/**
+* Formats a value as inline code, or as `_none_` if the value is blank.
+*/
+function codeOrNone(text) {
+	return text.trim() === "" ? "_none_" : code(text);
+}
+/**
+* Formats a text as inline code. Pipes are escaped to keep tables intact.
+*/
+function code(text) {
+	return `\`${text.replaceAll("|", "\\|")}\``;
+}
+//#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 markdownDocument("CSP Report", [{
+		heading: "Detected Directives",
+		content: markdownTableOrNone(["Directive", "Value"], maskNonces(directives).map((directive) => [code(directive.name), formatValues(directive.values)]))
+	}, {
+		heading: "Recommendations",
+		content: markdownEntriesOrNone(recommendations)
+	}]);
+}
+/**
+* Masks all nonce sources of a `Content-Security-Policy` header as
+* `'nonce-[NONCE_0]'`, `'nonce-[NONCE_1]'`, … and normalizes its formatting.
+*/
+function maskCspNonces(header) {
+	return maskNonces(parseCsp(header)).map((directive) => [directive.name, ...directive.values].join(" ")).join("; ");
+}
+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) => ({
+			name: 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) {
+	return codeOrNone(values.join(" "));
+}
+//#endregion
+//#region src/security/response-header-report.ts
+const ACTION_ORDER = [
+	"add",
+	"change",
+	"remove"
+];
+const MIN_HSTS_MAX_AGE = 31536e3;
+const PERMISSIONS_POLICY = "geolocation=(), microphone=(), camera=()";
+const RECOMMENDED_COMMON_HEADERS = [
+	{ name: "cache-control" },
+	{ name: "content-security-policy" },
+	{ name: "content-type" },
+	{
+		name: "cross-origin-opener-policy",
+		recommended: "same-origin"
+	},
+	{
+		name: "cross-origin-resource-policy",
+		recommended: "same-origin"
+	},
+	{
+		name: "strict-transport-security",
+		recommended: `max-age=${MIN_HSTS_MAX_AGE}; includeSubDomains`,
+		isAccepted: isStrictHsts
+	},
+	{
+		name: "x-content-type-options",
+		recommended: "nosniff"
+	},
+	{ name: "x-robots-tag" }
+];
+const DISCOURAGED_COMMON_HEADERS = ["access-control-allow-origin"];
+const RECOMMENDED_DOCUMENT_HEADERS = [
+	...RECOMMENDED_COMMON_HEADERS,
+	{
+		name: "permissions-policy",
+		recommended: PERMISSIONS_POLICY,
+		isAccepted: isRestrictivePermissionsPolicy
+	},
+	{
+		name: "referrer-policy",
+		recommended: "no-referrer"
+	},
+	{
+		name: "x-frame-options",
+		recommended: "DENY"
+	}
+];
+const DISCOURAGED_DOCUMENT_HEADERS = [...DISCOURAGED_COMMON_HEADERS, "x-xss-protection"];
+const RECOMMENDED_HEADERS = {
+	document: RECOMMENDED_DOCUMENT_HEADERS,
+	api: RECOMMENDED_COMMON_HEADERS
+};
+const DISCOURAGED_HEADERS = {
+	document: DISCOURAGED_DOCUMENT_HEADERS,
+	api: DISCOURAGED_COMMON_HEADERS
+};
+/**
+* Returns all headers of a response, or an empty object if the response is
+* missing. For page responses, this uses `response.allHeaders()`, which in
+* contrast to `response.headers()` includes security-related headers.
+*/
+async function getResponseHeaders(response) {
+	if (response === null) return {};
+	return "allHeaders" in response ? await response.allHeaders() : response.headers();
+}
+/**
+* Evaluates the headers of a response against a set of recommended security
+* headers and returns the result as a Markdown report.
+*
+* The report lists all evaluated headers of the response, followed by
+* recommendations for missing or deviating headers and for discouraged headers
+* to remove. Unrelated headers like `date` are omitted to keep the report
+* deterministic for file snapshots.
+*
+* @example
+* ```ts
+* const response = await page.goto("/");
+* const headers = await getResponseHeaders(response);
+*
+* expect(responseHeaderReport(headers, { type: "document" })).toMatchTextFile({
+*   fileExtension: "md",
+* });
+* ```
+*/
+function responseHeaderReport(headers, options) {
+	const recommendedHeaders = RECOMMENDED_HEADERS[options.type];
+	const discouragedHeaders = DISCOURAGED_HEADERS[options.type];
+	const headersByName = new Map(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
+	const detectedHeaders = [...recommendedHeaders.map((recommended) => recommended.name), ...discouragedHeaders].flatMap((name) => {
+		const value = headersByName.get(name);
+		return value === void 0 ? [] : [{
+			name,
+			value
+		}];
+	});
+	const recommendations = [...recommendedHeaders.flatMap((recommended) => evaluateHeader(recommended, headersByName.get(recommended.name))), ...discouragedHeaders.filter((name) => headersByName.has(name)).map((name) => ({
+		name,
+		action: "remove",
+		message: "Remove header"
+	}))].sort((a, b) => ACTION_ORDER.indexOf(a.action) - ACTION_ORDER.indexOf(b.action));
+	return markdownDocument("Response Header Report", [{
+		heading: "Detected Headers",
+		content: markdownTableOrNone(["Header", "Value"], detectedHeaders.map((header) => [code(header.name), formatValue(header)]))
+	}, {
+		heading: "Recommendations",
+		content: markdownEntriesOrNone(recommendations)
+	}]);
+}
+function evaluateHeader(recommended, value) {
+	if (value === void 0) return [{
+		name: recommended.name,
+		action: "add",
+		message: recommended.recommended === void 0 ? "Missing, add header" : `Missing, add ${code(recommended.recommended)}`
+	}];
+	if (recommended.recommended === void 0 || isAcceptedValue(recommended, value)) return [];
+	return [{
+		name: recommended.name,
+		action: "change",
+		message: `Change value to ${code(recommended.recommended)}`
+	}];
+}
+/**
+* Accepts a value if it passes the custom check of the header, or otherwise
+* if it equals the recommended value ignoring case and whitespace.
+*/
+function isAcceptedValue(recommended, value) {
+	if (recommended.isAccepted !== void 0) return recommended.isAccepted(value);
+	return recommended.recommended === void 0 || normalizeValue(value) === normalizeValue(recommended.recommended);
+}
+function isStrictHsts(value) {
+	const directives = normalizeValue(value).split("; ");
+	const maxAge = directives.find((directive) => directive.startsWith("max-age="))?.slice(8).replaceAll("\"", "");
+	return maxAge !== void 0 && Number(maxAge) >= MIN_HSTS_MAX_AGE && directives.includes("includesubdomains");
+}
+/**
+* Accepts a policy if it restricts at least the recommended permissions, so
+* stricter policies restricting further permissions are accepted as well.
+*/
+function isRestrictivePermissionsPolicy(value) {
+	const actualPermissions = parsePermissionsPolicy(value);
+	return Array.from(parsePermissionsPolicy(PERMISSIONS_POLICY)).every((permission) => actualPermissions.has(permission));
+}
+function parsePermissionsPolicy(value) {
+	return new Set(value.split(",").map(normalizeValue));
+}
+/**
+* Normalizes a header value for comparison by ignoring case, whitespace and
+* empty `;`-separated parts.
+*/
+function normalizeValue(value) {
+	return value.toLowerCase().split(";").map((part) => part.trim().replaceAll(/\s+/g, " ")).filter((part) => part !== "").join("; ");
+}
+function formatValue(header) {
+	return codeOrNone(header.name === "content-security-policy" ? maskCspNonces(header.value) : header.value);
+}
+//#endregion
 //#region src/file.ts
 /**
 * Resolves the given path segments against the root directory of the closest
@@ -990,26 +1405,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 +1420,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, getResponseHeaders, hasLogLevel, interceptRoute, isCI, maskBaseURL, maskedValue, maskedValueWithIndex, matchPath, modifyJsonBody, modifyTextBody, resolveFromPackageRoot, responseHeaderReport, roleLocators };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/playwright-utils",
-  "version": "0.8.0",
+  "version": "0.10.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": {