@flow-like/widget-bundler 0.1.1

package/src/csp-reason.ts

@@ -0,0 +1,307 @@
+// Mirror of `validate_widget_csp_reason` / `fold_widget_csp_reason` in
+// packages/wasm/schema/src/widget_policy.rs and of reason rule 8 in
+// packages/wasm/schema/src/widget_sources/text.rs. Driven by the reason
+// sections of packages/wasm/schema/tests/fixtures/widget_csp.json and
+// widget_source_classification.json.
+
+import { isIcannTld } from "./psl";
+
+export type WidgetCspReasonRejection =
+	| "reason-empty"
+	| "reason-not-nfc"
+	| "reason-forbidden-character"
+	| "reason-whitespace"
+	| "reason-length"
+	| "reason-too-few-letters"
+	| "reason-mixed-script"
+	| "reason-contains-address"
+	| "reason-mentions-product"
+	| "reason-claims-assurance"
+	| "reason-claims-attribution"
+	| "reason-duplicate";
+
+export const CSP_REASON_REJECTION_MESSAGES: Readonly<
+	Record<WidgetCspReasonRejection, string>
+> = {
+	"reason-empty": "reason is empty",
+	"reason-not-nfc": "reason must be NFC-normalized",
+	"reason-forbidden-character":
+		"reason may only contain letters, marks (at most 2 in a row), numbers, spaces and , . : ; ( ) - ' / &",
+	"reason-whitespace":
+		"reason must not start or end with a space or contain two spaces in a row",
+	"reason-length": "reason must be 8 to 120 characters long",
+	"reason-too-few-letters": "reason must contain at least 3 letters",
+	"reason-mixed-script":
+		"reason mixes ASCII letters with letters of another script in one word",
+	"reason-contains-address":
+		"reason must not contain web addresses, email addresses or domain names",
+	"reason-mentions-product": "reason must not mention Flow-Like",
+	"reason-claims-assurance":
+		"reason must not claim that sources are verified, trusted, approved, official, certified, secure or safe",
+	"reason-claims-attribution":
+		"reason of a purpose with inputs must not claim who provides the addresses",
+	"reason-duplicate": "reasons of two purposes must differ",
+};
+
+/** `<message> (<code>)`, the form Rust uses inside contract errors. */
+export function cspReasonProblem(rejection: WidgetCspReasonRejection): string {
+	return `${CSP_REASON_REJECTION_MESSAGES[rejection]} (${rejection})`;
+}
+
+const MIN_CHARS = 8;
+const MAX_CHARS = 120;
+const MAX_UTF16_UNITS = MAX_CHARS * 2;
+const MIN_LETTERS = 3;
+const MAX_MARK_RUN = 2;
+const PUNCTUATION = new Set([",", ".", ":", ";", "(", ")", "-", "'", "/", "&"]);
+const PRODUCT = "flowlike";
+const ASSURANCE_WORDS = new Set([
+	"verified",
+	"trusted",
+	"approved",
+	"official",
+	"certified",
+	"secure",
+	"securely",
+	"safe",
+	"safely",
+]);
+const ATTRIBUTION_WORDS = new Set([
+	"app",
+	"apps",
+	"application",
+	"admin",
+	"admins",
+	"administrator",
+	"administrators",
+	"organization",
+	"organisation",
+	"company",
+	"workspace",
+	"project",
+	"owner",
+]);
+const IDEOGRAPHIC_FULL_STOP = "\u3002";
+
+const ALPHABETIC = /^\p{Alphabetic}$/u;
+const MARK = /^\p{M}$/u;
+const NUMERIC = /^\p{N}$/u;
+const LONE_SURROGATE = /\p{Cs}/u;
+// Default_Ignorable_Code_Point of Unicode 15.1, the ranges of
+// `is_default_ignorable` in widget_policy.rs.
+const DEFAULT_IGNORABLE_RANGES: readonly (readonly [number, number])[] = [
+	[0x00ad, 0x00ad],
+	[0x034f, 0x034f],
+	[0x061c, 0x061c],
+	[0x115f, 0x1160],
+	[0x17b4, 0x17b5],
+	[0x180b, 0x180f],
+	[0x200b, 0x200f],
+	[0x202a, 0x202e],
+	[0x2060, 0x206f],
+	[0x3164, 0x3164],
+	[0xfe00, 0xfe0f],
+	[0xfeff, 0xfeff],
+	[0xffa0, 0xffa0],
+	[0xfff0, 0xfff8],
+	[0x1bca0, 0x1bca3],
+	[0x1d173, 0x1d17a],
+	[0xe0000, 0xe0fff],
+];
+
+const isAlphabetic = (c: string) => ALPHABETIC.test(c);
+const isMark = (c: string) => MARK.test(c);
+const isNumeric = (c: string) => NUMERIC.test(c);
+export const isDefaultIgnorable = (c: string) => {
+	const code = c.codePointAt(0) ?? 0;
+	return DEFAULT_IGNORABLE_RANGES.some(
+		([first, last]) => code >= first && code <= last,
+	);
+};
+const isAscii = (c: string) => (c.codePointAt(0) ?? 0) < 0x80;
+const isAsciiAlphanumeric = (c: string | undefined) =>
+	c !== undefined && /^[A-Za-z0-9]$/.test(c);
+const isLetterOrMark = (c: string) => isAlphabetic(c) || isMark(c);
+const isLatinExtended = (c: string) => {
+	const code = c.codePointAt(0) ?? 0;
+	return (code >= 0xc0 && code <= 0x24f) || (code >= 0x1e00 && code <= 0x1eff);
+};
+
+function isJoinable(c: string | undefined): boolean {
+	return c !== undefined && !isAscii(c) && isLetterOrMark(c);
+}
+
+function charactersAllowed(chars: readonly string[]): boolean {
+	let markRun = 0;
+	for (const [position, c] of chars.entries()) {
+		const joiner =
+			(c === "\u200c" || c === "\u200d") &&
+			position > 0 &&
+			isJoinable(chars[position - 1]) &&
+			isJoinable(chars[position + 1]);
+		if (joiner) {
+			markRun = 0;
+			continue;
+		}
+		if (isDefaultIgnorable(c)) return false;
+		if (isMark(c)) {
+			markRun += 1;
+			if (markRun > MAX_MARK_RUN) return false;
+			continue;
+		}
+		markRun = 0;
+		if (!(isAlphabetic(c) || isNumeric(c) || c === " " || PUNCTUATION.has(c))) {
+			return false;
+		}
+	}
+	return true;
+}
+
+/**
+ * Reason rule 3: the character allowlist. Default-ignorable code points are
+ * refused, except U+200C/U+200D between non-ASCII letters or marks. TS also
+ * rejects lone surrogates.
+ */
+export function reasonCharactersAllowed(reason: string): boolean {
+	return !LONE_SURROGATE.test(reason) && charactersAllowed(Array.from(reason));
+}
+
+function splitRuns(
+	chars: readonly string[],
+	keep: (c: string) => boolean,
+): string[][] {
+	const runs: string[][] = [[]];
+	for (const c of chars) {
+		if (keep(c)) runs[runs.length - 1]?.push(c);
+		else runs.push([]);
+	}
+	return runs;
+}
+
+/** Reason rule 7: a letter run mixing ASCII and non-Latin letters. */
+export function reasonHasMixedScript(reason: string): boolean {
+	return splitRuns(Array.from(reason), isLetterOrMark).some(
+		(run) =>
+			run.some((c) => isAscii(c) && isAlphabetic(c)) &&
+			run.some((c) => isAlphabetic(c) && !isAscii(c) && !isLatinExtended(c)),
+	);
+}
+
+function replaceIdeographicStops(chars: readonly string[]): string[] {
+	return chars.map((c, position) =>
+		c === IDEOGRAPHIC_FULL_STOP &&
+		isAsciiAlphanumeric(chars[position - 1]) &&
+		isAsciiAlphanumeric(chars[position + 1])
+			? "."
+			: c,
+	);
+}
+
+/**
+ * The form rules 9–12 of spec §14.2.4 compare, as `fold_widget_csp_reason`:
+ * `f` (NFKC, U+3002 between ASCII alphanumerics read as `.`, lowercase),
+ * decomposed with NFKD and stripped of marks and default-ignorable code
+ * points.
+ */
+export function foldWidgetCspReason(reason: string): string {
+	const folded = replaceIdeographicStops(Array.from(reason.normalize("NFKC")))
+		.join("")
+		.toLowerCase()
+		.normalize("NFKD");
+	return Array.from(folded)
+		.filter((c) => !isMark(c) && !isDefaultIgnorable(c))
+		.join("");
+}
+
+/** Whether a reason has more than 120 scalars, without walking a long one. */
+function exceedsMaxLength(reason: string): boolean {
+	if (reason.length > MAX_UTF16_UNITS) return true;
+	let scalars = 0;
+	for (const _ of reason) scalars += 1;
+	return scalars > MAX_CHARS;
+}
+
+function reasonWords(folded: string): string[] {
+	return splitRuns(
+		Array.from(folded),
+		(c) => isAlphabetic(c) || isNumeric(c) || isMark(c),
+	)
+		.filter((run) => run.length > 0)
+		.map((run) => run.join(""));
+}
+
+/**
+ * Reason rules 1–7 and 9–11 of §14.2.4, in order; the first failure is the
+ * code. A reason over 120 scalars fails with `reason-length` before any other
+ * rule looks at it. Rule 8 ({@link reasonContainsAddress}) and rule 12
+ * (duplicates across purposes) run separately.
+ */
+export function validateWidgetCspReason(
+	reason: string,
+	hasInputs: boolean,
+): WidgetCspReasonRejection | null {
+	if (reason.length === 0) return "reason-empty";
+	if (exceedsMaxLength(reason)) return "reason-length";
+	if (reason.normalize("NFC") !== reason) return "reason-not-nfc";
+	if (!reasonCharactersAllowed(reason)) return "reason-forbidden-character";
+	if (reason.startsWith(" ") || reason.endsWith(" ") || reason.includes("  ")) {
+		return "reason-whitespace";
+	}
+	const chars = Array.from(reason);
+	if (chars.length < MIN_CHARS) return "reason-length";
+	if (chars.filter(isAlphabetic).length < MIN_LETTERS) {
+		return "reason-too-few-letters";
+	}
+	if (reasonHasMixedScript(reason)) return "reason-mixed-script";
+	const skeleton = foldWidgetCspReason(reason);
+	const lettersAndNumbers = Array.from(skeleton)
+		.filter((c) => isAlphabetic(c) || isNumeric(c))
+		.join("");
+	if (lettersAndNumbers.includes(PRODUCT)) return "reason-mentions-product";
+	const words = reasonWords(skeleton);
+	if (words.some((word) => ASSURANCE_WORDS.has(word))) {
+		return "reason-claims-assurance";
+	}
+	if (hasInputs && words.some((word) => ATTRIBUTION_WORDS.has(word))) {
+		return "reason-claims-attribution";
+	}
+	return null;
+}
+
+/**
+ * Reason rule 8 `reason-contains-address` as `reason_contains_address`: a
+ * URL scheme, `@`, `www.`, or a dotted token whose last label has at least two
+ * characters and is non-ASCII or an ICANN TLD. Publish and bundler only.
+ */
+export function reasonContainsAddress(reason: string): boolean {
+	const folded = replaceIdeographicStops(
+		Array.from(reason.normalize("NFKC").toLowerCase()),
+	).join("");
+	if (
+		folded.includes("://") ||
+		folded.includes("@") ||
+		folded.includes("www.")
+	) {
+		return true;
+	}
+	return splitRuns(
+		Array.from(folded),
+		(c) => isLetterOrMark(c) || isNumeric(c) || c === "-" || c === ".",
+	).some((run) => {
+		const labels = run
+			.join("")
+			.replace(/^\.+|\.+$/g, "")
+			.split(".");
+		const last = labels[labels.length - 1] ?? "";
+		return (
+			labels.length >= 2 &&
+			Array.from(last).length >= 2 &&
+			(!Array.from(last).every(isAscii) || isIcannTld(last))
+		);
+	});
+}
+
+/** Normalization applied to authored reasons: NFC, collapsed whitespace, trimmed. */
+export function normalizeCspReason(reason: string): string {
+	return reason.normalize("NFC").replace(/\s+/g, " ").trim();
+}

package/src/csp-source.ts

@@ -0,0 +1,361 @@
+// Mirror of the source grammar, limits and input path grammar in
+// packages/wasm/schema/src/widget_policy.rs. Both implementations are driven
+// by packages/wasm/schema/tests/fixtures/widget_csp.json. No local runtime
+// imports: tests load this module under Node as well.
+
+import { domainToASCII } from "node:url";
+import type {
+	WidgetCsp,
+	WidgetCspDirective,
+	WidgetCspPurpose,
+} from "@flow-like/widget-sdk";
+
+export const MAX_WIDGET_CSP_SOURCES = 16;
+export const MAX_WIDGET_CSP_SOURCE_BYTES = 1536;
+export const MAX_WIDGET_CSP_PURPOSES = 8;
+export const MAX_WIDGET_NETWORK_INPUTS = 8;
+export const MAX_WIDGET_INPUT_PATH_SEGMENTS = 6;
+export const MAX_WIDGET_TEMPLATE_SUBDOMAINS = 16;
+
+/** Widget inputs the host injects itself; network inputs never read them. */
+export const HOST_RESERVED_INPUT_KEYS: readonly string[] = [
+	"publicMediaGrants",
+];
+
+/** Contract keys in the order serde serializes them (`CspDirective::ALL`) */
+export const CSP_DIRECTIVES = [
+	"connectSrc",
+	"imgSrc",
+	"fontSrc",
+	"mediaSrc",
+	"styleSrc",
+] as const satisfies readonly WidgetCspDirective[];
+
+export type CspDirective = WidgetCspDirective;
+
+export const CSP_PURPOSE_KEYS = [
+	"reason",
+	...CSP_DIRECTIVES,
+	"inputs",
+] as const;
+
+export const CSP_NETWORK_INPUT_KEYS = [
+	"path",
+	"directives",
+	"template",
+] as const;
+export const CSP_TEMPLATE_KEYS = ["subdomains", "subdomainsInput"] as const;
+
+export const CSP_ALLOWED_SCHEMES: Readonly<
+	Record<CspDirective, readonly string[]>
+> = {
+	connectSrc: ["https", "wss"],
+	imgSrc: ["https"],
+	fontSrc: ["https"],
+	mediaSrc: ["https"],
+	styleSrc: ["https"],
+};
+
+export type CspSourceRejection =
+	| "empty"
+	| "non-ascii"
+	| "wildcard"
+	| "keyword"
+	| "forbidden-character"
+	| "uppercase"
+	| "userinfo"
+	| "query-or-fragment"
+	| "ip-literal"
+	| "missing-scheme"
+	| "scheme-not-allowed"
+	| "port"
+	| "path"
+	| "invalid-host"
+	| "reserved-name";
+
+export const CSP_SOURCE_REJECTION_MESSAGES: Readonly<
+	Record<CspSourceRejection, string>
+> = {
+	empty: "source is empty",
+	"non-ascii": "non-ASCII characters are not allowed (use punycode)",
+	wildcard: 'wildcards are only allowed as a leading "*." label of the host',
+	keyword: "keywords, nonces and hashes are not allowed",
+	"forbidden-character": "contains a forbidden character",
+	uppercase: "uppercase characters are not allowed",
+	userinfo: "userinfo is not allowed",
+	"query-or-fragment": "queries and fragments are not allowed",
+	"ip-literal": "IP literals are not allowed",
+	"missing-scheme": "must have the form scheme://host",
+	"scheme-not-allowed": "scheme is not allowed for this directive",
+	port: "ports are not allowed",
+	path: "paths are not allowed",
+	"invalid-host": "host is not a valid public DNS name",
+	"reserved-name": "host uses a reserved or local-only name",
+};
+
+const MAX_HOST_LEN = 253;
+
+const RESERVED_NAME_SUFFIXES = [
+	"localhost",
+	"local",
+	"internal",
+	"lan",
+	"home.arpa",
+	"test",
+	"example",
+	"invalid",
+	"onion",
+	"nip.io",
+	"sslip.io",
+	"traefik.me",
+	"localtest.me",
+	"lvh.me",
+	"localhost.direct",
+];
+
+const SOURCE_CHARSET = /^[a-z0-9.:/*-]+$/;
+const WILDCARD_FORM = /^[a-z]+:\/\/\*\.[^*]+$/;
+const DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const MEMBER_KEY = /^[A-Za-z_][A-Za-z0-9_]*/;
+
+export function isCspDirective(key: string): key is CspDirective {
+	return (CSP_DIRECTIVES as readonly string[]).includes(key);
+}
+
+function hasNonAscii(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		if (value.charCodeAt(index) > 0x7f) return true;
+	}
+	return false;
+}
+
+/** ASCII whitespace or control characters, `;`, `,` and quotes */
+function hasForbiddenDelimiter(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code <= 0x20 || code === 0x7f || ";,\"'".includes(value[index] ?? "")) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Checks one declared source against the grammar
+ * `scheme "://" [ "*." ] host` and returns the first failing check, in the
+ * same order as `validate_csp_source` in Rust. Public suffix checks on
+ * wildcard bases live in `validateWildcardBases`.
+ */
+export function validateCspSource(
+	directive: CspDirective,
+	source: string,
+): CspSourceRejection | null {
+	if (source.length === 0) return "empty";
+	if (hasNonAscii(source)) return "non-ascii";
+	if (source.includes("*") && !WILDCARD_FORM.test(source)) return "wildcard";
+	if (source.startsWith("'")) return "keyword";
+	if (hasForbiddenDelimiter(source)) return "forbidden-character";
+	if (/[A-Z]/.test(source)) return "uppercase";
+	if (source.includes("@")) return "userinfo";
+	if (/[?#]/.test(source)) return "query-or-fragment";
+	if (/[[\]]/.test(source)) return "ip-literal";
+	if (!SOURCE_CHARSET.test(source)) return "forbidden-character";
+	const separator = source.indexOf("://");
+	if (separator <= 0) return "missing-scheme";
+	if (!CSP_ALLOWED_SCHEMES[directive].includes(source.slice(0, separator))) {
+		return "scheme-not-allowed";
+	}
+	const rest = source.slice(separator + 3);
+	const hostEnd = rest.search(/[:/]/);
+	if (hostEnd !== -1) return rest[hostEnd] === ":" ? "port" : "path";
+	return rest.startsWith("*.")
+		? validateHost(rest.slice(2), MAX_HOST_LEN - 2)
+		: validateHost(rest, MAX_HOST_LEN);
+}
+
+function validateHost(host: string, maxLen: number): CspSourceRejection | null {
+	if (host.length === 0 || host.length > maxLen) return "invalid-host";
+	const labels = host.split(".");
+	if (labels.some((label) => label.length === 0)) return "invalid-host";
+	const tld = labels[labels.length - 1] ?? "";
+	if (/^[0-9]+$/.test(tld)) return "ip-literal";
+	if (!labels.every((label) => DNS_LABEL.test(label))) return "invalid-host";
+	if (RESERVED_NAME_SUFFIXES.some((suffix) => hostMatches(host, suffix))) {
+		return "reserved-name";
+	}
+	if (labels.length < 2 || !isTld(tld)) return "invalid-host";
+	return null;
+}
+
+function isTld(label: string): boolean {
+	return label.startsWith("xn--")
+		? /^[a-z0-9-]{1,59}$/.test(label.slice(4))
+		: /^[a-z]{2,63}$/.test(label);
+}
+
+function hostMatches(host: string, reserved: string): boolean {
+	return (
+		host === reserved ||
+		(host.endsWith(reserved) && host[host.length - reserved.length - 1] === ".")
+	);
+}
+
+export function isDnsLabel(label: string): boolean {
+	return DNS_LABEL.test(label);
+}
+
+const ENCODER = new TextEncoder();
+
+/** UTF-8 byte order, which is how Rust orders `String`s. */
+export function compareCspSources(a: string, b: string): number {
+	if (a === b) return 0;
+	const left = ENCODER.encode(a);
+	const right = ENCODER.encode(b);
+	const length = Math.min(left.length, right.length);
+	for (let index = 0; index < length; index++) {
+		const difference = (left[index] ?? 0) - (right[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return left.length - right.length;
+}
+
+export function isStrictlyAscending(
+	items: readonly string[],
+	compare: (a: string, b: string) => number = compareCspSources,
+): boolean {
+	return items.every(
+		(item, index) => index === 0 || compare(items[index - 1] ?? "", item) < 0,
+	);
+}
+
+/** An ASCII character a DNS host cannot contain; non-ASCII is left to IDNA */
+const FORBIDDEN_HOST_ASCII = /[^a-z0-9.€-￿-]/;
+
+/**
+ * `domainToASCII` runs the runtime's own URL host parser: Node strips tabs,
+ * splits on backslashes, percent-decodes and refuses mapped hosts that end in
+ * a number or contain forbidden code points, Bun does none of that. Only a
+ * host without such ASCII whose result is a well-formed DNS name is taken,
+ * so both runtimes agree.
+ */
+function punycodeHost(host: string): string | null {
+	if (FORBIDDEN_HOST_ASCII.test(host)) return null;
+	const ascii = domainToASCII(host);
+	const rejection = validateHost(ascii, MAX_HOST_LEN);
+	return rejection === null || rejection === "reserved-name" ? ascii : null;
+}
+
+/**
+ * Authoring normalization: lowercases the source and converts an
+ * internationalized host (or wildcard base) to punycode. Anything the grammar
+ * rejects is left for `validateCspSource` to report.
+ */
+export function normalizeCspSource(source: string): string {
+	const lowered = source.toLowerCase();
+	const separator = lowered.indexOf("://");
+	if (separator <= 0) return lowered;
+	const prefix = lowered.slice(0, separator + 3);
+	const rest = lowered.slice(separator + 3);
+	const hostEnd = rest.search(/[:/?#]/);
+	const authority = hostEnd === -1 ? rest : rest.slice(0, hostEnd);
+	const wildcard = authority.startsWith("*.") ? "*." : "";
+	const host = authority.slice(wildcard.length);
+	if (!hasNonAscii(host)) return lowered;
+	const ascii = punycodeHost(host);
+	if (ascii === null) return lowered;
+	return `${prefix}${wildcard}${ascii}${hostEnd === -1 ? "" : rest.slice(hostEnd)}`;
+}
+
+/** Sorted ascending in UTF-8 byte order without duplicates. */
+export function canonicalCspSources(sources: readonly string[]): string[] {
+	return [...new Set(sources)].sort(compareCspSources);
+}
+
+export function isCspEmpty(csp: WidgetCsp): boolean {
+	return CSP_DIRECTIVES.every(
+		(directive) => (csp[directive]?.length ?? 0) === 0,
+	);
+}
+
+export function cspSourceCount(csp: WidgetCsp): number {
+	return CSP_DIRECTIVES.reduce(
+		(count, directive) => count + (csp[directive]?.length ?? 0),
+		0,
+	);
+}
+
+/** Σ(len + 1) over every entry: the bytes the sources add to a header. */
+export function cspSourceBytes(csp: WidgetCsp): number {
+	return CSP_DIRECTIVES.reduce(
+		(bytes, directive) =>
+			bytes +
+			(csp[directive] ?? []).reduce(
+				(sum, source) => sum + ENCODER.encode(source).length + 1,
+				0,
+			),
+		0,
+	);
+}
+
+/** Per-directive union of every purpose's sources (`flatten_csp_purposes`). */
+export function flattenCspPurposes(
+	purposes: readonly WidgetCspPurpose[],
+): WidgetCsp {
+	const csp: WidgetCsp = {};
+	for (const directive of CSP_DIRECTIVES) {
+		const sources = canonicalCspSources(
+			purposes.flatMap((purpose) => purpose[directive] ?? []),
+		);
+		if (sources.length > 0) csp[directive] = sources;
+	}
+	return csp;
+}
+
+export type WidgetInputPathSegment =
+	| { kind: "key"; key: string }
+	| { kind: "items" }
+	| { kind: "values" };
+
+export interface WidgetInputPath {
+	root: string;
+	segments: WidgetInputPathSegment[];
+}
+
+/** Parses `root *( "." key / "[]" / ".*" )` with `key = [A-Za-z_][A-Za-z0-9_]*`. */
+export function parseWidgetInputPath(path: string): WidgetInputPath | null {
+	const root = MEMBER_KEY.exec(path)?.[0];
+	if (root === undefined) return null;
+	const segments: WidgetInputPathSegment[] = [];
+	let rest = path.slice(root.length);
+	while (rest.length > 0) {
+		if (rest.startsWith("[]")) {
+			segments.push({ kind: "items" });
+			rest = rest.slice(2);
+		} else if (rest.startsWith(".*")) {
+			segments.push({ kind: "values" });
+			rest = rest.slice(2);
+		} else {
+			const key = rest.startsWith(".")
+				? MEMBER_KEY.exec(rest.slice(1))?.[0]
+				: undefined;
+			if (key === undefined) return null;
+			segments.push({ kind: "key", key });
+			rest = rest.slice(1 + key.length);
+		}
+	}
+	return { root, segments };
+}
+
+export function isValidWidgetInputPath(path: string): boolean {
+	const parsed = parseWidgetInputPath(path);
+	return (
+		parsed !== null && parsed.segments.length < MAX_WIDGET_INPUT_PATH_SEGMENTS
+	);
+}
+
+export function compareCspDirectives(a: string, b: string): number {
+	return (
+		CSP_DIRECTIVES.indexOf(a as CspDirective) -
+		CSP_DIRECTIVES.indexOf(b as CspDirective)
+	);
+}