@cronn/playwright-utils 0.9.0 → 0.10.0

package/dist/index.d.mts

@@ -618,6 +618,38 @@ export declare function getCspHeader(response: Response | null): Promise<string>
  */
 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
@@ -757,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

@@ -791,6 +791,41 @@ 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" },
@@ -899,13 +934,20 @@ async function getCspHeader(response) {
 */
 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");
+	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) => {
@@ -922,7 +964,7 @@ function evaluateCsp(directives) {
 	return {
 		directives,
 		recommendations: RECOMMENDED_DIRECTIVES.flatMap((recommended) => evaluateDirective(recommended, directivesByName).map((message) => ({
-			directive: recommended.name,
+			name: recommended.name,
 			message
 		})))
 	};
@@ -983,11 +1025,164 @@ function isNonce(value) {
 	return value.startsWith("'nonce-");
 }
 function formatValues(values) {
-	if (values.length === 0) return "_none_";
-	return code(values.join(" "));
+	return codeOrNone(values.join(" "));
 }
-function code(text) {
-	return `\`${text.replaceAll("|", "\\|")}\``;
+//#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
@@ -1225,4 +1420,4 @@ function identity(value) {
 	return value;
 }
 //#endregion
-export { ConsoleCaptor, CspCaptor, RouteInterceptor, RouteInterceptorFixture, captureConsole, captureCspViolations, createFetchAdapter, cspFixtures, cspReport, extendLocator, formFiller, getCspHeader, 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.9.0",
+  "version": "0.10.0",
   "description": "Utilities for writing tests with Playwright",
   "keywords": [
     "playwright",