@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/author-css.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The CSS-spec URL guaranteed never to load, used as the replacement.
+ *
+ * Substituting this rather than deleting the declaration keeps the CSS
+ * grammar valid in every position `url()` is valid — `background: url(x)
+ * no-repeat` stays a well-formed shorthand — so a refused URL costs the
+ * author one image and never corrupts the rest of their stylesheet.
+ */
+export declare const INERT_CSS_URL = "about:invalid";
+/**
+ * Whether a `url()` target must be replaced with {@link INERT_CSS_URL}.
+ *
+ * The actor analysis behind the narrow rule, because it is the whole reason
+ * this is not `isFirstPartyMediaSrc` (AGL-1701):
+ *
+ * - In AGL-1701 the URL came from a **marketplace publisher** and was
+ *   rendered to **other orgs' users**. Aglyn put a stranger's host in front
+ *   of people who had no dealing with that publisher, so Aglyn introduced
+ *   the recipient and restricting the input was right.
+ * - Here the URL comes from the **site owner**, rendered to **the site
+ *   owner's own visitors**, on the site owner's own domain. The site owner
+ *   is the controller for those visitors and Aglyn is the processor; they
+ *   are choosing a recipient for data they already control, which is what a
+ *   controller does when they add a font, a pixel or a hotlinked image.
+ *   Aglyn did not introduce the recipient and should not silently veto it.
+ *
+ * Same shape of finding, opposite answer, because the actor and the victim
+ * are in a different relationship. What survives is the scheme rule, which
+ * protects the visitor without taking the host decision away from the owner.
+ */
+export declare function isRefusedAuthorCssUrl(target: string): boolean;
+/**
+ * Whether an author-typed image `src` must not be rendered at all.
+ *
+ * The {@link isRefusedAuthorCssUrl} scheme rule applied to a plain `<img
+ * src>` sink rather than a CSS `url()` token. Same actor pair — the site
+ * owner supplies the URL, their own visitors fetch it — so the same
+ * decision: never the host, only the scheme. `http:` and every unknown
+ * scheme are refused (the AGL-1713 rule); `https:`, `data:`, `blob:`,
+ * protocol-relative and the site-relative forms the media picker stores
+ * (`/api/media/cdn/…`) all render.
+ *
+ * A refused `media:` reference is CORRECT here, not collateral: this
+ * helper is for the sinks that emit the stored string RAW, where a media
+ * reference would render as the literal `src="media:…"` — a request for a
+ * relative path that cannot resolve. Sinks that resolve references first
+ * (`resolveMediaSrc` callers) have no use for this function.
+ *
+ * For AGL-1725's inventory: the free-text sinks that render the stored
+ * value verbatim — the events cover, the marketing popup image — are the
+ * callers; each was an `http:`-accepting egress no other guard reached.
+ */
+export declare function isRefusedAuthorImageSrc(src: string): boolean;
+/**
+ * Rewrites every refused `url()` in an author stylesheet to
+ * {@link INERT_CSS_URL}, leaving the rest of the CSS byte-identical.
+ *
+ * Returns the input BY IDENTITY when nothing is refused, which is the
+ * overwhelmingly common case and lets callers on a render path skip work.
+ */
+export declare function sanitizeAuthorCss(css: string): string;
+/**
+ * The third-party hosts a stylesheet's `url()` tokens would make a
+ * visitor's browser contact (AGL-1737).
+ *
+ * This is the WARN half of AGL-1725's warn-and-disclose decision, for the
+ * Styles panel: the scheme filter above ships, the host is deliberately not
+ * restricted, and that decision is only honest if the author is told what
+ * the `url()` they typed will do. This helper feeds a passive caption in
+ * the panel — it never blocks, rewrites, or validates anything.
+ *
+ * What is collected: the hostname of every `https:` (and protocol-relative,
+ * which resolves against the https document) `url()` target that is not one
+ * of OUR hosts — `isFirstPartyHost` is the same first-party set `media-ref`
+ * keeps in sync with `security-origins.js`. What is deliberately not:
+ *
+ * - refused schemes (`http:`, `javascript:`, …) — {@link sanitizeAuthorCss}
+ *   rewrites them to {@link INERT_CSS_URL} at render, so they contact
+ *   nobody and naming them as an egress would be false;
+ * - `data:` / `blob:` / relative forms — no request leaves the machine, or
+ *   it stays on the author's own origin.
+ *
+ * Hostnames are lowercased, deduped, and returned in first-appearance
+ * order, ready to be named back to the author verbatim.
+ */
+export declare function collectThirdPartyAuthorCssUrlHosts(css: string): string[];
+/**
+ * {@link collectThirdPartyAuthorCssUrlHosts} over an `sx` object — the
+ * shape the Styles panel's builder and JSON tabs hold (AGL-1737). Walks
+ * arrays and nested records exactly as {@link sanitizeAuthorSx} does and
+ * unions the hosts found in string leaves, preserving first-appearance
+ * order across the whole document.
+ */
+export declare function collectThirdPartyAuthorSxUrlHosts(sx: unknown): string[];
+/**
+ * {@link sanitizeAuthorCss} over an `sx` object from the Styles panel.
+ *
+ * Walks arrays (MUI's composition form), nested records (selectors, media
+ * queries, breakpoint slices) and scrubs string leaves. Non-string,
+ * non-walkable values — numbers, functions, null — pass through untouched.
+ *
+ * Identity is preserved for any subtree that did not change, so a node whose
+ * styles hold no `url()` at all (nearly all of them) gets its own object
+ * back and nothing downstream re-renders. That matches the contract
+ * `resolvePaletteVarsSx` already states on the same render path.
+ */
+export declare function sanitizeAuthorSx<T>(sx: T): T;

package/src/lib/app-utils/author-css.js

@@ -0,0 +1,275 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Scheme rules for `url()` inside AUTHOR-WRITTEN CSS (AGL-1725).
+ *
+ * Two surfaces on a published tenant site put author CSS into the visitor's
+ * document verbatim, and neither is reachable by any control we had:
+ *
+ * 1. the `css` attribute of the Custom HTML component, emitted as a raw
+ *    `<style>` block (`custom-html.tsx`) — DOMPurify there is applied to the
+ *    `html` attribute ONLY and never sees this string;
+ * 2. `node.sx` from the Styles panel, where `backgroundImage` is a
+ *    first-class field and the Custom CSS tab is free-solo, so any property
+ *    and any value can be typed.
+ *
+ * `aglyn/no-remote-image-service` cannot see either — it scans OUR source for
+ * host literals, and these arrive at runtime from Firestore. No input
+ * validator sees them either: they are free-text CSS, not a URL field.
+ *
+ * ## What this module does and, deliberately, does not do
+ *
+ * It does **not** restrict which HOST an author may reach over `https:`.
+ * That is the AGL-1701 remedy, and it does not transfer here — see the note
+ * on {@link isRefusedAuthorCssUrl}. Hotlinking is an advertised authoring
+ * feature (`image.tsx` tells authors to "paste the URL of an image hosted
+ * somewhere else"), the author is the site owner, and the report-only
+ * `img-src` shipped for AGL-1703 now measures the practice for the first
+ * time. Restricting a host list before the first measurement would break
+ * live customer sites silently to prevent something nobody has counted.
+ *
+ * It **does** refuse a scheme that cannot be defended at any volume:
+ * anything that is not `https:`, `data:`, `blob:` or same-document.
+ * `http:` is the case that matters — mixed passive content on an HTTPS page
+ * is already blocked or auto-upgraded by every current browser, so the
+ * author gains nothing from it, while the request discloses what the visitor
+ * is reading to every observer on the path rather than only to the host the
+ * author chose. AGL-1701 found two other paths accepting `http:`
+ * (`markdown-lite.ts`, `collection-fallback-nodes.ts`); this is the same
+ * rule reaching the two CSS surfaces.
+ */ import { isFirstPartyHost } from "./media-ref.js";
+/**
+ * The CSS-spec URL guaranteed never to load, used as the replacement.
+ *
+ * Substituting this rather than deleting the declaration keeps the CSS
+ * grammar valid in every position `url()` is valid — `background: url(x)
+ * no-repeat` stays a well-formed shorthand — so a refused URL costs the
+ * author one image and never corrupts the rest of their stylesheet.
+ */ export const INERT_CSS_URL = 'about:invalid';
+/**
+ * Schemes an author's `url()` may name.
+ *
+ * `data:` and `blob:` are in because they are inert: the bytes are already
+ * in the document and no request leaves the machine. `https:` is in because
+ * restricting it is a product decision this module does not take.
+ */ const ALLOWED_CSS_URL_SCHEMES = [
+    'https:',
+    'data:',
+    'blob:'
+];
+/**
+ * Matches one `url(...)` token, quoted or bare, capturing the target.
+ *
+ * Bare targets cannot contain `)` unescaped per the CSS grammar, so the
+ * negated class is right for them; quoted targets may, so they are matched
+ * to their closing quote. A bare target using a CSS escape (`url(\68 ttps:`)
+ * is NOT decoded here and will therefore be refused — fail-closed on an
+ * encoding nobody writes by hand, which costs an author who could simply
+ * type the URL nothing.
+ */ const CSS_URL_TOKEN = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^)\s'"]*))\s*\)/gi;
+/**
+ * Whether a `url()` target must be replaced with {@link INERT_CSS_URL}.
+ *
+ * The actor analysis behind the narrow rule, because it is the whole reason
+ * this is not `isFirstPartyMediaSrc` (AGL-1701):
+ *
+ * - In AGL-1701 the URL came from a **marketplace publisher** and was
+ *   rendered to **other orgs' users**. Aglyn put a stranger's host in front
+ *   of people who had no dealing with that publisher, so Aglyn introduced
+ *   the recipient and restricting the input was right.
+ * - Here the URL comes from the **site owner**, rendered to **the site
+ *   owner's own visitors**, on the site owner's own domain. The site owner
+ *   is the controller for those visitors and Aglyn is the processor; they
+ *   are choosing a recipient for data they already control, which is what a
+ *   controller does when they add a font, a pixel or a hotlinked image.
+ *   Aglyn did not introduce the recipient and should not silently veto it.
+ *
+ * Same shape of finding, opposite answer, because the actor and the victim
+ * are in a different relationship. What survives is the scheme rule, which
+ * protects the visitor without taking the host decision away from the owner.
+ */ export function isRefusedAuthorCssUrl(target) {
+    const trimmed = target.trim();
+    // An empty url() names nothing and issues no request.
+    if (!trimmed) return false;
+    // Protocol-relative: resolves against the document, which is https on a
+    // published site, so it can never become the mixed-content case.
+    if (trimmed.startsWith('//')) return false;
+    // Same-document / same-origin forms.
+    if (trimmed.startsWith('/') || trimmed.startsWith('#') || trimmed.startsWith('./') || trimmed.startsWith('../')) {
+        return false;
+    }
+    // A scheme is everything before the first `:`, but only when that `:`
+    // precedes any path, query or fragment delimiter — otherwise `a:b` inside
+    // a relative path would read as a scheme.
+    const colon = trimmed.indexOf(':');
+    if (colon <= 0) return false;
+    const beforeColon = trimmed.slice(0, colon);
+    if (/[/?#]/.test(beforeColon)) return false;
+    return !ALLOWED_CSS_URL_SCHEMES.includes(`${beforeColon.toLowerCase()}:`);
+}
+/**
+ * Whether an author-typed image `src` must not be rendered at all.
+ *
+ * The {@link isRefusedAuthorCssUrl} scheme rule applied to a plain `<img
+ * src>` sink rather than a CSS `url()` token. Same actor pair — the site
+ * owner supplies the URL, their own visitors fetch it — so the same
+ * decision: never the host, only the scheme. `http:` and every unknown
+ * scheme are refused (the AGL-1713 rule); `https:`, `data:`, `blob:`,
+ * protocol-relative and the site-relative forms the media picker stores
+ * (`/api/media/cdn/…`) all render.
+ *
+ * A refused `media:` reference is CORRECT here, not collateral: this
+ * helper is for the sinks that emit the stored string RAW, where a media
+ * reference would render as the literal `src="media:…"` — a request for a
+ * relative path that cannot resolve. Sinks that resolve references first
+ * (`resolveMediaSrc` callers) have no use for this function.
+ *
+ * For AGL-1725's inventory: the free-text sinks that render the stored
+ * value verbatim — the events cover, the marketing popup image — are the
+ * callers; each was an `http:`-accepting egress no other guard reached.
+ */ export function isRefusedAuthorImageSrc(src) {
+    return isRefusedAuthorCssUrl(src);
+}
+/**
+ * Rewrites every refused `url()` in an author stylesheet to
+ * {@link INERT_CSS_URL}, leaving the rest of the CSS byte-identical.
+ *
+ * Returns the input BY IDENTITY when nothing is refused, which is the
+ * overwhelmingly common case and lets callers on a render path skip work.
+ */ export function sanitizeAuthorCss(css) {
+    if (!css || !css.includes('url(')) return css;
+    let changed = false;
+    const next = css.replace(CSS_URL_TOKEN, (match, quoted, single, bare)=>{
+        var _ref, _ref1;
+        const target = (_ref = (_ref1 = quoted != null ? quoted : single) != null ? _ref1 : bare) != null ? _ref : '';
+        if (!isRefusedAuthorCssUrl(target)) return match;
+        changed = true;
+        return `url(${INERT_CSS_URL})`;
+    });
+    return changed ? next : css;
+}
+/**
+ * The third-party hosts a stylesheet's `url()` tokens would make a
+ * visitor's browser contact (AGL-1737).
+ *
+ * This is the WARN half of AGL-1725's warn-and-disclose decision, for the
+ * Styles panel: the scheme filter above ships, the host is deliberately not
+ * restricted, and that decision is only honest if the author is told what
+ * the `url()` they typed will do. This helper feeds a passive caption in
+ * the panel — it never blocks, rewrites, or validates anything.
+ *
+ * What is collected: the hostname of every `https:` (and protocol-relative,
+ * which resolves against the https document) `url()` target that is not one
+ * of OUR hosts — `isFirstPartyHost` is the same first-party set `media-ref`
+ * keeps in sync with `security-origins.js`. What is deliberately not:
+ *
+ * - refused schemes (`http:`, `javascript:`, …) — {@link sanitizeAuthorCss}
+ *   rewrites them to {@link INERT_CSS_URL} at render, so they contact
+ *   nobody and naming them as an egress would be false;
+ * - `data:` / `blob:` / relative forms — no request leaves the machine, or
+ *   it stays on the author's own origin.
+ *
+ * Hostnames are lowercased, deduped, and returned in first-appearance
+ * order, ready to be named back to the author verbatim.
+ */ export function collectThirdPartyAuthorCssUrlHosts(css) {
+    if (!css || !css.includes('url(')) return [];
+    const hosts = [];
+    const seen = new Set();
+    for (const match of css.matchAll(CSS_URL_TOKEN)){
+        var _ref, _ref1, _match_;
+        const target = ((_ref = (_ref1 = (_match_ = match[1]) != null ? _match_ : match[2]) != null ? _ref1 : match[3]) != null ? _ref : '').trim();
+        if (!target || isRefusedAuthorCssUrl(target)) continue;
+        let hostname;
+        try {
+            // Protocol-relative inherits the published page's https.
+            hostname = new URL(target.startsWith('//') ? `https:${target}` : target).hostname;
+        } catch (unused) {
+            continue; // relative path — same-origin, no third party
+        }
+        // `data:`/`blob:` parse with an empty hostname; nothing to name.
+        if (!hostname) continue;
+        const lower = hostname.toLowerCase();
+        if (isFirstPartyHost(lower) || seen.has(lower)) continue;
+        seen.add(lower);
+        hosts.push(lower);
+    }
+    return hosts;
+}
+/**
+ * {@link collectThirdPartyAuthorCssUrlHosts} over an `sx` object — the
+ * shape the Styles panel's builder and JSON tabs hold (AGL-1737). Walks
+ * arrays and nested records exactly as {@link sanitizeAuthorSx} does and
+ * unions the hosts found in string leaves, preserving first-appearance
+ * order across the whole document.
+ */ export function collectThirdPartyAuthorSxUrlHosts(sx) {
+    const hosts = [];
+    const seen = new Set();
+    const visit = (value)=>{
+        if (typeof value === 'string') {
+            for (const hostname of collectThirdPartyAuthorCssUrlHosts(value)){
+                if (seen.has(hostname)) continue;
+                seen.add(hostname);
+                hosts.push(hostname);
+            }
+            return;
+        }
+        if (!value || typeof value !== 'object') return;
+        if (Array.isArray(value)) {
+            for (const entry of value)visit(entry);
+            return;
+        }
+        for (const key of Object.keys(value)){
+            visit(value[key]);
+        }
+    };
+    visit(sx);
+    return hosts;
+}
+/**
+ * {@link sanitizeAuthorCss} over an `sx` object from the Styles panel.
+ *
+ * Walks arrays (MUI's composition form), nested records (selectors, media
+ * queries, breakpoint slices) and scrubs string leaves. Non-string,
+ * non-walkable values — numbers, functions, null — pass through untouched.
+ *
+ * Identity is preserved for any subtree that did not change, so a node whose
+ * styles hold no `url()` at all (nearly all of them) gets its own object
+ * back and nothing downstream re-renders. That matches the contract
+ * `resolvePaletteVarsSx` already states on the same render path.
+ */ export function sanitizeAuthorSx(sx) {
+    if (typeof sx === 'string') return sanitizeAuthorCss(sx);
+    if (!sx || typeof sx !== 'object') return sx;
+    if (Array.isArray(sx)) {
+        let changed = false;
+        const next = sx.map((entry)=>{
+            const value = sanitizeAuthorSx(entry);
+            if (value !== entry) changed = true;
+            return value;
+        });
+        return changed ? next : sx;
+    }
+    let changed = false;
+    const next = {};
+    for (const key of Object.keys(sx)){
+        const entry = sx[key];
+        const value = sanitizeAuthorSx(entry);
+        if (value !== entry) changed = true;
+        next[key] = value;
+    }
+    return changed ? next : sx;
+}
+
+//# sourceMappingURL=author-css.js.map

package/src/lib/app-utils/author-css.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/author-css.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Scheme rules for `url()` inside AUTHOR-WRITTEN CSS (AGL-1725).\n *\n * Two surfaces on a published tenant site put author CSS into the visitor's\n * document verbatim, and neither is reachable by any control we had:\n *\n * 1. the `css` attribute of the Custom HTML component, emitted as a raw\n *    `<style>` block (`custom-html.tsx`) — DOMPurify there is applied to the\n *    `html` attribute ONLY and never sees this string;\n * 2. `node.sx` from the Styles panel, where `backgroundImage` is a\n *    first-class field and the Custom CSS tab is free-solo, so any property\n *    and any value can be typed.\n *\n * `aglyn/no-remote-image-service` cannot see either — it scans OUR source for\n * host literals, and these arrive at runtime from Firestore. No input\n * validator sees them either: they are free-text CSS, not a URL field.\n *\n * ## What this module does and, deliberately, does not do\n *\n * It does **not** restrict which HOST an author may reach over `https:`.\n * That is the AGL-1701 remedy, and it does not transfer here — see the note\n * on {@link isRefusedAuthorCssUrl}. Hotlinking is an advertised authoring\n * feature (`image.tsx` tells authors to \"paste the URL of an image hosted\n * somewhere else\"), the author is the site owner, and the report-only\n * `img-src` shipped for AGL-1703 now measures the practice for the first\n * time. Restricting a host list before the first measurement would break\n * live customer sites silently to prevent something nobody has counted.\n *\n * It **does** refuse a scheme that cannot be defended at any volume:\n * anything that is not `https:`, `data:`, `blob:` or same-document.\n * `http:` is the case that matters — mixed passive content on an HTTPS page\n * is already blocked or auto-upgraded by every current browser, so the\n * author gains nothing from it, while the request discloses what the visitor\n * is reading to every observer on the path rather than only to the host the\n * author chose. AGL-1701 found two other paths accepting `http:`\n * (`markdown-lite.ts`, `collection-fallback-nodes.ts`); this is the same\n * rule reaching the two CSS surfaces.\n */\n\nimport { isFirstPartyHost } from './media-ref'\n\n/**\n * The CSS-spec URL guaranteed never to load, used as the replacement.\n *\n * Substituting this rather than deleting the declaration keeps the CSS\n * grammar valid in every position `url()` is valid — `background: url(x)\n * no-repeat` stays a well-formed shorthand — so a refused URL costs the\n * author one image and never corrupts the rest of their stylesheet.\n */\nexport const INERT_CSS_URL = 'about:invalid'\n\n/**\n * Schemes an author's `url()` may name.\n *\n * `data:` and `blob:` are in because they are inert: the bytes are already\n * in the document and no request leaves the machine. `https:` is in because\n * restricting it is a product decision this module does not take.\n */\nconst ALLOWED_CSS_URL_SCHEMES = ['https:', 'data:', 'blob:']\n\n/**\n * Matches one `url(...)` token, quoted or bare, capturing the target.\n *\n * Bare targets cannot contain `)` unescaped per the CSS grammar, so the\n * negated class is right for them; quoted targets may, so they are matched\n * to their closing quote. A bare target using a CSS escape (`url(\\68 ttps:`)\n * is NOT decoded here and will therefore be refused — fail-closed on an\n * encoding nobody writes by hand, which costs an author who could simply\n * type the URL nothing.\n */\nconst CSS_URL_TOKEN = /url\\(\\s*(?:\"([^\"]*)\"|'([^']*)'|([^)\\s'\"]*))\\s*\\)/gi\n\n/**\n * Whether a `url()` target must be replaced with {@link INERT_CSS_URL}.\n *\n * The actor analysis behind the narrow rule, because it is the whole reason\n * this is not `isFirstPartyMediaSrc` (AGL-1701):\n *\n * - In AGL-1701 the URL came from a **marketplace publisher** and was\n *   rendered to **other orgs' users**. Aglyn put a stranger's host in front\n *   of people who had no dealing with that publisher, so Aglyn introduced\n *   the recipient and restricting the input was right.\n * - Here the URL comes from the **site owner**, rendered to **the site\n *   owner's own visitors**, on the site owner's own domain. The site owner\n *   is the controller for those visitors and Aglyn is the processor; they\n *   are choosing a recipient for data they already control, which is what a\n *   controller does when they add a font, a pixel or a hotlinked image.\n *   Aglyn did not introduce the recipient and should not silently veto it.\n *\n * Same shape of finding, opposite answer, because the actor and the victim\n * are in a different relationship. What survives is the scheme rule, which\n * protects the visitor without taking the host decision away from the owner.\n */\nexport function isRefusedAuthorCssUrl(target: string): boolean {\n  const trimmed = target.trim()\n  // An empty url() names nothing and issues no request.\n  if (!trimmed) return false\n  // Protocol-relative: resolves against the document, which is https on a\n  // published site, so it can never become the mixed-content case.\n  if (trimmed.startsWith('//')) return false\n  // Same-document / same-origin forms.\n  if (\n    trimmed.startsWith('/') ||\n    trimmed.startsWith('#') ||\n    trimmed.startsWith('./') ||\n    trimmed.startsWith('../')\n  ) {\n    return false\n  }\n  // A scheme is everything before the first `:`, but only when that `:`\n  // precedes any path, query or fragment delimiter — otherwise `a:b` inside\n  // a relative path would read as a scheme.\n  const colon = trimmed.indexOf(':')\n  if (colon <= 0) return false\n  const beforeColon = trimmed.slice(0, colon)\n  if (/[/?#]/.test(beforeColon)) return false\n  return !ALLOWED_CSS_URL_SCHEMES.includes(`${beforeColon.toLowerCase()}:`)\n}\n\n/**\n * Whether an author-typed image `src` must not be rendered at all.\n *\n * The {@link isRefusedAuthorCssUrl} scheme rule applied to a plain `<img\n * src>` sink rather than a CSS `url()` token. Same actor pair — the site\n * owner supplies the URL, their own visitors fetch it — so the same\n * decision: never the host, only the scheme. `http:` and every unknown\n * scheme are refused (the AGL-1713 rule); `https:`, `data:`, `blob:`,\n * protocol-relative and the site-relative forms the media picker stores\n * (`/api/media/cdn/…`) all render.\n *\n * A refused `media:` reference is CORRECT here, not collateral: this\n * helper is for the sinks that emit the stored string RAW, where a media\n * reference would render as the literal `src=\"media:…\"` — a request for a\n * relative path that cannot resolve. Sinks that resolve references first\n * (`resolveMediaSrc` callers) have no use for this function.\n *\n * For AGL-1725's inventory: the free-text sinks that render the stored\n * value verbatim — the events cover, the marketing popup image — are the\n * callers; each was an `http:`-accepting egress no other guard reached.\n */\nexport function isRefusedAuthorImageSrc(src: string): boolean {\n  return isRefusedAuthorCssUrl(src)\n}\n\n/**\n * Rewrites every refused `url()` in an author stylesheet to\n * {@link INERT_CSS_URL}, leaving the rest of the CSS byte-identical.\n *\n * Returns the input BY IDENTITY when nothing is refused, which is the\n * overwhelmingly common case and lets callers on a render path skip work.\n */\nexport function sanitizeAuthorCss(css: string): string {\n  if (!css || !css.includes('url(')) return css\n  let changed = false\n  const next = css.replace(\n    CSS_URL_TOKEN,\n    (match, quoted: string, single: string, bare: string) => {\n      const target = quoted ?? single ?? bare ?? ''\n      if (!isRefusedAuthorCssUrl(target)) return match\n      changed = true\n      return `url(${INERT_CSS_URL})`\n    },\n  )\n  return changed ? next : css\n}\n\n/**\n * The third-party hosts a stylesheet's `url()` tokens would make a\n * visitor's browser contact (AGL-1737).\n *\n * This is the WARN half of AGL-1725's warn-and-disclose decision, for the\n * Styles panel: the scheme filter above ships, the host is deliberately not\n * restricted, and that decision is only honest if the author is told what\n * the `url()` they typed will do. This helper feeds a passive caption in\n * the panel — it never blocks, rewrites, or validates anything.\n *\n * What is collected: the hostname of every `https:` (and protocol-relative,\n * which resolves against the https document) `url()` target that is not one\n * of OUR hosts — `isFirstPartyHost` is the same first-party set `media-ref`\n * keeps in sync with `security-origins.js`. What is deliberately not:\n *\n * - refused schemes (`http:`, `javascript:`, …) — {@link sanitizeAuthorCss}\n *   rewrites them to {@link INERT_CSS_URL} at render, so they contact\n *   nobody and naming them as an egress would be false;\n * - `data:` / `blob:` / relative forms — no request leaves the machine, or\n *   it stays on the author's own origin.\n *\n * Hostnames are lowercased, deduped, and returned in first-appearance\n * order, ready to be named back to the author verbatim.\n */\nexport function collectThirdPartyAuthorCssUrlHosts(css: string): string[] {\n  if (!css || !css.includes('url(')) return []\n  const hosts: string[] = []\n  const seen = new Set<string>()\n  for (const match of css.matchAll(CSS_URL_TOKEN)) {\n    const target = (match[1] ?? match[2] ?? match[3] ?? '').trim()\n    if (!target || isRefusedAuthorCssUrl(target)) continue\n    let hostname: string\n    try {\n      // Protocol-relative inherits the published page's https.\n      hostname = new URL(\n        target.startsWith('//') ? `https:${target}` : target,\n      ).hostname\n    } catch {\n      continue // relative path — same-origin, no third party\n    }\n    // `data:`/`blob:` parse with an empty hostname; nothing to name.\n    if (!hostname) continue\n    const lower = hostname.toLowerCase()\n    if (isFirstPartyHost(lower) || seen.has(lower)) continue\n    seen.add(lower)\n    hosts.push(lower)\n  }\n  return hosts\n}\n\n/**\n * {@link collectThirdPartyAuthorCssUrlHosts} over an `sx` object — the\n * shape the Styles panel's builder and JSON tabs hold (AGL-1737). Walks\n * arrays and nested records exactly as {@link sanitizeAuthorSx} does and\n * unions the hosts found in string leaves, preserving first-appearance\n * order across the whole document.\n */\nexport function collectThirdPartyAuthorSxUrlHosts(sx: unknown): string[] {\n  const hosts: string[] = []\n  const seen = new Set<string>()\n  const visit = (value: unknown): void => {\n    if (typeof value === 'string') {\n      for (const hostname of collectThirdPartyAuthorCssUrlHosts(value)) {\n        if (seen.has(hostname)) continue\n        seen.add(hostname)\n        hosts.push(hostname)\n      }\n      return\n    }\n    if (!value || typeof value !== 'object') return\n    if (Array.isArray(value)) {\n      for (const entry of value) visit(entry)\n      return\n    }\n    for (const key of Object.keys(value as Record<string, unknown>)) {\n      visit((value as Record<string, unknown>)[key])\n    }\n  }\n  visit(sx)\n  return hosts\n}\n\n/**\n * {@link sanitizeAuthorCss} over an `sx` object from the Styles panel.\n *\n * Walks arrays (MUI's composition form), nested records (selectors, media\n * queries, breakpoint slices) and scrubs string leaves. Non-string,\n * non-walkable values — numbers, functions, null — pass through untouched.\n *\n * Identity is preserved for any subtree that did not change, so a node whose\n * styles hold no `url()` at all (nearly all of them) gets its own object\n * back and nothing downstream re-renders. That matches the contract\n * `resolvePaletteVarsSx` already states on the same render path.\n */\nexport function sanitizeAuthorSx<T>(sx: T): T {\n  if (typeof sx === 'string') return sanitizeAuthorCss(sx) as unknown as T\n  if (!sx || typeof sx !== 'object') return sx\n  if (Array.isArray(sx)) {\n    let changed = false\n    const next = sx.map((entry) => {\n      const value = sanitizeAuthorSx(entry)\n      if (value !== entry) changed = true\n      return value\n    })\n    return (changed ? next : sx) as unknown as T\n  }\n  let changed = false\n  const next: Record<string, unknown> = {}\n  for (const key of Object.keys(sx as Record<string, unknown>)) {\n    const entry = (sx as Record<string, unknown>)[key]\n    const value = sanitizeAuthorSx(entry)\n    if (value !== entry) changed = true\n    next[key] = value\n  }\n  return (changed ? next : sx) as unknown as T\n}\n"],"names":["isFirstPartyHost","INERT_CSS_URL","ALLOWED_CSS_URL_SCHEMES","CSS_URL_TOKEN","isRefusedAuthorCssUrl","target","trimmed","trim","startsWith","colon","indexOf","beforeColon","slice","test","includes","toLowerCase","isRefusedAuthorImageSrc","src","sanitizeAuthorCss","css","changed","next","replace","match","quoted","single","bare","collectThirdPartyAuthorCssUrlHosts","hosts","seen","Set","matchAll","hostname","URL","lower","has","add","push","collectThirdPartyAuthorSxUrlHosts","sx","visit","value","Array","isArray","entry","key","Object","keys","sanitizeAuthorSx","map"],"mappings":"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"}

package/src/lib/app-utils/author-html-markdown.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** Where relative URLs resolve, matching `PageMarkdownContext`. */
+export interface AuthorHtmlMarkdownContext {
+    origin?: string | null;
+    hostId?: string;
+}
+/** Author HTML as Markdown blocks — headings, lists, links, code and all. */
+export declare function authorHtmlToMarkdown(html: string, context?: AuthorHtmlMarkdownContext): string;
+/**
+ * A control's rich label as ONE line of Markdown.
+ *
+ * Block structure is deliberately flattened: a button whose label is a heading
+ * is not a heading, and emitting one would put a `#` in the middle of a
+ * sentence for every rich-mode label on the site.
+ */
+export declare function inlineAuthorHtmlToMarkdown(html: string, context?: AuthorHtmlMarkdownContext): string;