@mpgd/cli 0.28.1 → 0.30.0

package/dist/hosted-pwa-deployment.js

@@ -0,0 +1,1264 @@
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, realpathSync, statSync, } from 'node:fs';
+import { dirname, join, posix, relative, resolve } from 'node:path';
+import { decodeHTMLAttribute } from 'entities';
+import { cloudflarePagesPathMatches, evaluateCloudflarePagesHeader, normalizeHeaderDirectiveValue, parseCloudflarePagesHeaders, parseCloudflarePagesRedirects, } from './cloudflare-pages-static.js';
+import { createMicrosoftStorePwaRevisionFromFiles, createMicrosoftStorePwaServiceWorker, listPrecacheUrls, readMicrosoftStorePwaReleaseEvidence, } from './microsoft-store-pwa-release.js';
+/**
+ * Read-only verification that a hosted Cloudflare Pages deployment directory
+ * serves exactly the files of an already-verified PWA artifact, with routing
+ * and cache headers that keep the PWA entry points reachable and fresh.
+ *
+ * The verifier knows nothing about individual games or workspace layouts: it
+ * compares an explicit source artifact directory against an explicit
+ * deployment directory under one of the reviewed Pages host profiles.
+ */
+export const hostedPwaDeploymentHosts = ['cloudflare-pages'];
+export const cloudflarePagesDeploymentProfiles = ['api-only', 'api-canonical-index'];
+/** Host files that Pages adds around the game artifact. */
+const cloudflarePagesHostFileAllowlist = new Set([
+    '_worker.js',
+    '_headers',
+    '_redirects',
+    '_routes.json',
+    'wrangler.jsonc',
+    'legal-site.json',
+]);
+/** SVG presentation attributes whose url() values load external resources. */
+const svgUrlAttributeNames = new Set([
+    'fill',
+    'stroke',
+    'filter',
+    'clip-path',
+    'mask',
+    'marker-start',
+    'marker-mid',
+    'marker-end',
+]);
+/** Control artifacts Pages consumes instead of serving to browsers. */
+const pagesControlArtifactNames = new Set([
+    '_worker.js',
+    '_headers',
+    '_redirects',
+    '_routes.json',
+    'wrangler.jsonc',
+]);
+/** Request paths a redirect may never cover, matched as patterns. */
+const protectedPwaMetadataRequestPaths = [
+    '/',
+    '/index.html',
+    '/manifest.webmanifest',
+    '/service-worker.js',
+    '/pwa-release.json',
+];
+const freshCacheControl = 'public, max-age=0, must-revalidate';
+const noStoreCacheControl = 'no-store, must-revalidate';
+const immutableCacheControl = 'public, max-age=31536000, immutable';
+const freshCacheControlFiles = new Set([
+    '/manifest.webmanifest',
+    '/pwa-release.json',
+    '/mpgd-effective-target.json',
+    '/mpgd-icon-manifest.json',
+    '/mpgd-icon-precache.json',
+    '/legal-site.json',
+    '/game-services-routing.json',
+]);
+const noStoreCacheControlFiles = new Set(['/service-worker.js']);
+const immutableCacheControlDirectories = new Set(['assets']);
+const noStoreCacheControlDirectories = new Set(['icons']);
+/** Precache URLs the reviewed PWA contract always includes. */
+const requiredPrecacheUrls = new Set([
+    './index.html',
+    './manifest.webmanifest',
+    './pwa-release.json',
+]);
+export function isSupportedHostedPwaProfile(host, profile) {
+    if (!hostedPwaDeploymentHosts.includes(host)) {
+        return false;
+    }
+    return cloudflarePagesDeploymentProfiles.includes(profile);
+}
+export function verifyHostedPwaDeployment(input) {
+    if (!hostedPwaDeploymentHosts.includes(input.host)) {
+        throw new Error(`Unsupported hosted PWA deployment host: ${input.host} `
+            + `(supported: ${hostedPwaDeploymentHosts.join(', ')}).`);
+    }
+    if (!cloudflarePagesDeploymentProfiles.includes(input.profile)) {
+        throw new Error(`Unsupported Cloudflare Pages host profile: ${input.profile} `
+            + `(supported: ${cloudflarePagesDeploymentProfiles.join(', ')}).`);
+    }
+    const sourceRoot = resolveArtifactDirectory(input.sourceArtifactRoot, 'source PWA artifact');
+    const deploymentRoot = resolveArtifactDirectory(input.deploymentRoot, 'deployment');
+    if (sourceRoot === deploymentRoot) {
+        throw new Error('The source artifact and the deployment directory must be different directories; '
+            + 'a self-comparison cannot validate the deployment merge.');
+    }
+    const sourceFiles = listArtifactFilesStrict(sourceRoot, 'source PWA artifact');
+    const deploymentFiles = listArtifactFilesStrict(deploymentRoot, 'deployment');
+    const evidence = verifySourceArtifactSelfConsistency(sourceRoot, sourceFiles);
+    verifyDeploymentGameFiles(sourceRoot, sourceFiles, deploymentRoot, deploymentFiles);
+    const hostFiles = verifyDeploymentFileClassification(deploymentFiles, sourceFiles, deploymentRoot, input.profile);
+    const referencedDirectoryUrls = verifyIndexReferences(deploymentRoot, deploymentFiles);
+    const workerRoutes = verifyCloudflarePagesRoutes(deploymentRoot, input.profile);
+    assertNoSourceRoutesShadowed(workerRoutes, sourceFiles, input.profile);
+    assertNoLegalRoutesShadowed(workerRoutes, [...readLegalSitePages(deploymentRoot)], input.profile);
+    const legalPages = [...readLegalSitePages(deploymentRoot)];
+    const declaredLegalDirectories = new Set(legalPages.map((page) => page.slice(0, -'index.html'.length)));
+    verifyCloudflarePagesHeaders(deploymentRoot, sourceFiles, deploymentFiles, declaredLegalDirectories, workerRoutes);
+    const deploymentLegalPaths = [
+        ...[...readLegalSitePages(deploymentRoot)].flatMap((page) => {
+            const directoryUrl = `/${page.slice(0, -'index.html'.length)}`;
+            return [directoryUrl, `/${page}`];
+        }),
+        ...(existsSync(join(deploymentRoot, 'legal-site.json'))
+            ? ['/legal-site.json']
+            : []),
+    ];
+    verifyCloudflarePagesRedirects(deploymentRoot, sourceFiles, deploymentLegalPaths, referencedDirectoryUrls);
+    return {
+        host: input.host,
+        profile: input.profile,
+        sourceArtifactRoot: sourceRoot,
+        deploymentRoot,
+        appVersion: evidence.appVersion,
+        buildId: evidence.buildId,
+        revision: evidence.revision,
+        verifiedGameFileCount: sourceFiles.length,
+        hostFileCount: hostFiles.length,
+        workerRoutes,
+    };
+}
+function resolveArtifactDirectory(path, label) {
+    const resolved = resolve(path);
+    if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+        throw new Error(`The ${label} directory does not exist: ${resolved}`);
+    }
+    return realpathSync(resolved);
+}
+/**
+ * Enumerate every file under a root with strict safety: symbolic links,
+ * non-regular files, and non-portable names are rejected so the deployment
+ * comparison cannot be redirected outside the inspected directory.
+ */
+function listArtifactFilesStrict(root, label) {
+    const files = [];
+    const pendingDirectories = [root];
+    while (pendingDirectories.length > 0) {
+        const directory = pendingDirectories.pop();
+        if (directory === undefined) {
+            throw new Error(`${label} traversal lost its directory.`);
+        }
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const absolute = join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`The ${label} must not contain symbolic links: ${absolute}`);
+            }
+            if (/[\\\t\n\r]/u.test(entry.name)) {
+                throw new Error(`The ${label} contains a non-portable file name with a backslash or `
+                    + `URL-stripped control character: ${JSON.stringify(entry.name)}`);
+            }
+            if (entry.isDirectory()) {
+                pendingDirectories.push(absolute);
+            }
+            else if (entry.isFile()) {
+                const relativePath = posix.normalize(relativePortablePath(root, absolute));
+                if (relativePath.startsWith('../')
+                    || relativePath === '..'
+                    || relativePath.includes('/../')
+                    || posix.isAbsolute(relativePath)) {
+                    throw new Error(`The ${label} file escapes its root: ${absolute}`);
+                }
+                // Digests stream from disk; bytes are retained only for the files
+                // whose content is parsed later, so large game assets are not held
+                // in memory during verification.
+                const digest = createHash('sha256');
+                const handle = openSync(absolute, 'r');
+                const chunk = Buffer.allocUnsafe(1024 * 1024);
+                try {
+                    let read = readSync(handle, chunk, 0, chunk.length, null);
+                    while (read > 0) {
+                        digest.update(chunk.subarray(0, read));
+                        read = readSync(handle, chunk, 0, chunk.length, null);
+                    }
+                }
+                finally {
+                    closeSync(handle);
+                }
+                files.push({
+                    path: relativePath,
+                    sha256: digest.digest('hex'),
+                });
+            }
+            else {
+                throw new Error(`The ${label} contains an entry that is neither a directory nor a regular `
+                    + `file: ${absolute}`);
+            }
+        }
+    }
+    return files.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+}
+function relativePortablePath(root, absolute) {
+    const rootReal = realpathSync(root);
+    const parentReal = realpathSync(dirname(absolute));
+    return relative(rootReal, join(parentReal, absolute.slice(dirname(absolute).length)))
+        .split('\\')
+        .join('/');
+}
+function verifySourceArtifactSelfConsistency(sourceRoot, sourceFiles) {
+    const evidencePath = `${sourceRoot}/pwa-release.json`;
+    if (!existsSync(evidencePath)) {
+        throw new Error('The source PWA artifact is missing pwa-release.json.');
+    }
+    const evidence = readMicrosoftStorePwaReleaseEvidence(evidencePath);
+    for (const reserved of cloudflarePagesHostFileAllowlist) {
+        if (sourceFiles.some((file) => file.path === reserved)) {
+            throw new Error(`The source PWA artifact contains the Pages control file ${reserved}; `
+                + 'control files belong to the host deployment, not the game artifact.');
+        }
+    }
+    for (const required of ['index.html', 'manifest.webmanifest', 'service-worker.js']) {
+        if (!sourceFiles.some((file) => file.path === required)) {
+            throw new Error(`The source PWA artifact is missing ${required}.`);
+        }
+    }
+    const manifest = JSON.parse(readFileSync(`${sourceRoot}/manifest.webmanifest`, 'utf8'));
+    if (manifest.id !== evidence.pwaId) {
+        throw new Error('The source PWA artifact manifest application id does not match the '
+            + 'release evidence; the manifest and pwa-release.json must identify '
+            + 'the same application.');
+    }
+    const enumeratedUrls = [
+        ...listPrecacheUrls(sourceRoot),
+        './pwa-release.json',
+    ].sort();
+    const recordedUrls = [...evidence.precacheUrls].sort();
+    if (JSON.stringify(enumeratedUrls) !== JSON.stringify(recordedUrls)) {
+        throw new Error('The source PWA artifact precache contract is inconsistent: the recorded '
+            + 'pwa-release.json URLs do not match the files actually present in the '
+            + 'artifact, so the service worker precache list cannot be trusted.');
+    }
+    for (const required of requiredPrecacheUrls) {
+        if (!evidence.precacheUrls.includes(required)) {
+            throw new Error(`The source PWA artifact precache contract omits the required URL ${required}.`);
+        }
+    }
+    const sourceWorker = sourceFiles.find((file) => file.path === 'service-worker.js');
+    if (sourceWorker !== undefined
+        && readFileSync(join(sourceRoot, 'service-worker.js'), 'utf8')
+            !== createMicrosoftStorePwaServiceWorker(evidence)) {
+        throw new Error('The source PWA artifact service worker does not match the release '
+            + 'evidence; it must be the deterministic worker generated for the '
+            + 'recorded precache contract so its cache identity and precache list '
+            + 'cannot drift from pwa-release.json.');
+    }
+    const recomputedRevision = createMicrosoftStorePwaRevisionFromFiles({
+        appVersion: evidence.appVersion,
+        buildId: evidence.buildId,
+        sourceGitSha: evidence.sourceGitSha,
+        kitGitSha: evidence.kitGitSha,
+        precacheUrls: evidence.precacheUrls,
+        artifactRoot: sourceRoot,
+    });
+    if (recomputedRevision !== evidence.revision) {
+        throw new Error('The source PWA artifact is not self-consistent: the recomputed release revision '
+            + `${recomputedRevision} does not match the recorded ${evidence.revision}.`);
+    }
+    return evidence;
+}
+function verifyDeploymentGameFiles(sourceRoot, sourceFiles, deploymentRoot, deploymentFiles) {
+    const deploymentByPath = new Map(deploymentFiles.map((file) => [file.path, file]));
+    for (const sourceFile of sourceFiles) {
+        const deployed = deploymentByPath.get(sourceFile.path);
+        if (deployed === undefined) {
+            throw new Error(`The deployment is missing game file ${sourceFile.path} `
+                + `from the source artifact ${sourceRoot}.`);
+        }
+        if (deployed.sha256 !== sourceFile.sha256) {
+            throw new Error(`The deployment game file ${sourceFile.path} does not match the source artifact; `
+                + `expected sha256 ${sourceFile.sha256} but found ${deployed.sha256}.`);
+        }
+    }
+}
+function verifyDeploymentFileClassification(deploymentFiles, sourceFiles, deploymentRoot, profile) {
+    const sourcePaths = new Set(sourceFiles.map((file) => file.path));
+    const legalPages = readLegalSitePages(deploymentRoot);
+    const hostFiles = [];
+    const unexpected = [];
+    for (const file of deploymentFiles) {
+        if (sourcePaths.has(file.path)) {
+            continue;
+        }
+        if (cloudflarePagesHostFileAllowlist.has(file.path) || legalPages.has(file.path)) {
+            hostFiles.push(file.path);
+            continue;
+        }
+        unexpected.push(file.path);
+    }
+    if (unexpected.length > 0) {
+        throw new Error('The deployment contains files that belong neither to the source artifact nor to '
+            + `the recognized Pages host files: ${unexpected.join(', ')}. `
+            + 'This usually means files from a different build were mixed into the deployment.');
+    }
+    // Both reviewed profiles route /api/* through the Pages worker, so a
+    // deployment without the worker would verify statically while shipping
+    // broken API routes.
+    if (!hostFiles.includes('_worker.js')) {
+        throw new Error(`The deployment is missing _worker.js; the reviewed ${profile} profile `
+            + 'routes /api/* through the Pages worker.');
+    }
+    return hostFiles;
+}
+function readLegalSitePages(deploymentRoot) {
+    const manifestPath = `${deploymentRoot}/legal-site.json`;
+    if (!existsSync(manifestPath)) {
+        return new Set();
+    }
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const pages = new Set();
+    if (typeof parsed !== 'object'
+        || parsed === null
+        || !Array.isArray(parsed.pages)) {
+        throw new Error('The deployment legal-site.json must declare a pages array.');
+    }
+    for (const page of parsed.pages) {
+        if (typeof page !== 'object' || page === null) {
+            throw new Error('The deployment legal-site.json page entries must be objects.');
+        }
+        const path = page.path;
+        const canonicalPath = typeof path === 'string'
+            && path.startsWith('/')
+            && path.endsWith('/')
+            && path !== '/'
+            && path
+                .slice(1, -1)
+                .split('/')
+                .every((segment) => /^[A-Za-z0-9_-]+$/u.test(segment));
+        if (!canonicalPath) {
+            throw new Error('The deployment legal-site.json page paths must be canonical slash-delimited '
+                + `URL pathnames without queries, fragments, dot segments, or escapes: ${String(path)}`);
+        }
+        const relativePage = `${path.slice(1)}index.html`;
+        const distance = relative(deploymentRoot, resolve(deploymentRoot, relativePage));
+        if (distance === '' || distance.startsWith('..') || posix.isAbsolute(distance)) {
+            throw new Error(`The deployment legal-site.json page path escapes the deployment root: ${path}`);
+        }
+        pages.add(relativePage);
+    }
+    for (const page of pages) {
+        const pageFile = join(deploymentRoot, page);
+        if (!existsSync(pageFile) || !statSync(pageFile).isFile()) {
+            throw new Error('The deployment legal-site.json declares a page that is not present as a '
+                + `regular file: ${page}`);
+        }
+    }
+    return pages;
+}
+function verifyIndexReferences(deploymentRoot, deploymentFiles) {
+    const index = deploymentFiles.find((file) => file.path === 'index.html');
+    if (index === undefined) {
+        throw new Error('The deployment is missing index.html.');
+    }
+    const rawHtml = readFileSync(join(deploymentRoot, 'index.html'), 'utf8');
+    const cssReferences = [];
+    const cssSourceHtml = stripScriptsAndComments(rawHtml);
+    for (const styleBody of cssSourceHtml.matchAll(/<style\b(?:(?:"[^"]*"|'[^']*'|[^>"])*)>([\s\S]*?)<\/style\s*>/giu)) {
+        collectInlineCssReferences(styleBody[1] ?? '', cssReferences);
+    }
+    const html = stripNonMarkupRanges(rawHtml);
+    if (/<base\b/iu.test(html)) {
+        throw new Error('The deployment index.html declares a base element; reference resolution '
+            + 'against a non-root document base is unsupported by this verifier.');
+    }
+    const deploymentPaths = new Set(deploymentFiles.map((file) => file.path));
+    const referenced = new Set();
+    const referencedDirectoryUrls = new Set();
+    const references = [...cssReferences];
+    const metaRefreshContents = [];
+    const embeddedDocuments = [];
+    const stylesheetHrefs = new Set();
+    const activeStylesheets = new Set();
+    // Attributes only exist on start tags; scanning raw text would treat prose
+    // like `Set href="..."` as a reference. Extract within element start tags,
+    // with object data URLs and srcset candidates handled per tag.
+    const startTagPattern = /<([A-Za-z][^\s/>]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/gu;
+    for (const tag of html.matchAll(startTagPattern)) {
+        const tagName = (tag[1] ?? '').toLowerCase();
+        const attributes = tag[2] ?? '';
+        const resourceNames = tagName === 'object'
+            ? ['href', 'src', 'poster', 'data']
+            : ['href', 'src', 'poster', 'xlink:href'];
+        // Tokenize real attribute name/value pairs exactly once so every
+        // attribute-driven check (resource names, srcset, style, srcdoc, meta)
+        // shares one parse. Quoted values of unrelated attributes
+        // (title='See srcset="./missing.png"') can never leak references, and
+        // duplicate attributes keep their first occurrence like HTML parsing.
+        const seenAttributeNames = new Set();
+        const attributePairs = [];
+        for (const attribute of attributes.matchAll(/([A-Za-z_:][-A-Za-z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gu)) {
+            const name = (attribute[1] ?? '').toLowerCase();
+            if (seenAttributeNames.has(name)) {
+                continue;
+            }
+            seenAttributeNames.add(name);
+            attributePairs.push({ name, value: attribute[2] ?? attribute[3] ?? attribute[4] ?? '' });
+        }
+        // An iframe srcdoc overrides src even when its value is empty.
+        const attributesHasSrcdoc = tagName === 'iframe'
+            && attributePairs.some(({ name }) => name === 'srcdoc');
+        let isMetaRefresh = false;
+        let metaContent;
+        let styleValue;
+        let srcsetValue;
+        let linkRel;
+        let linkHref;
+        for (const { name, value } of attributePairs) {
+            if (tagName === 'meta' && name === 'http-equiv' && value.trim().toLowerCase() === 'refresh') {
+                isMetaRefresh = true;
+            }
+            if (tagName === 'meta' && name === 'content') {
+                metaContent = value;
+            }
+            if (name === 'style') {
+                styleValue = value;
+            }
+            if (name === 'srcset') {
+                srcsetValue = value;
+            }
+            if (tagName === 'link' && name === 'rel') {
+                linkRel = value.trim().toLowerCase();
+            }
+            if (tagName === 'link' && name === 'href') {
+                linkHref = value;
+            }
+            if (!resourceNames.includes(name) && name !== 'srcdoc') {
+                continue;
+            }
+            if (name === 'srcdoc' && value.length > 0) {
+                // srcdoc embeds a document resolved relative to this one; scan its
+                // content for the same resource attributes.
+                embeddedDocuments.push(decodeHtmlReferences(value));
+                continue;
+            }
+            if (value.length > 0) {
+                if (tagName === 'iframe' && name === 'src' && attributesHasSrcdoc) {
+                    continue;
+                }
+                references.push(value);
+            }
+        }
+        // Remember stylesheet links by their raw href so only files the browser
+        // actually applies as CSS join the stylesheet scan; a plain anchor to a
+        // .css file is just a downloadable reference. rel/href order-agnostic.
+        if (tagName === 'link' && linkHref !== undefined && isStylesheetRel(linkRel)) {
+            stylesheetHrefs.add(linkHref);
+        }
+        if (isMetaRefresh && metaContent !== undefined) {
+            metaRefreshContents.push(metaContent);
+        }
+        if (styleValue !== undefined) {
+            collectInlineCssReferences(decodeHtmlReferences(styleValue), references);
+        }
+        if (srcsetValue === undefined) {
+            continue;
+        }
+        // Shared WHATWG srcset tokenizer (also used by the legal-page pass).
+        pushSrcsetCandidates(decodeHtmlReferences(srcsetValue), references);
+    }
+    // Embedded srcdoc documents resolve their resources against this
+    // deployment; scan them with the full tokenizer (resource attributes,
+    // srcset candidates, object data, and inline CSS alike).
+    for (const document of embeddedDocuments) {
+        collectEmbeddedDocumentReferences(document, references);
+    }
+    // Meta-refresh targets navigate automatically; treat the URL part of the
+    // content directive as a browser-loaded local reference.
+    for (const rawContent of metaRefreshContents) {
+        const content = decodeHtmlReferences(rawContent);
+        const target = /^[^;,]*[,;]\s*url\s*=\s*(?:"([^"]+)"|'([^']+)'|([^;,\s]+))/iu.exec(content);
+        if (target !== null) {
+            references.push(target[1] ?? target[2] ?? target[3] ?? '');
+        }
+    }
+    for (const rawReference of references) {
+        const reference = decodeHtmlReferences(rawReference).trim();
+        const schemeSeparated = /^([a-z][a-z0-9+.-]*):/iu.exec(reference);
+        if (reference.length === 0 || reference.startsWith('#') || reference.startsWith('data:')) {
+            continue;
+        }
+        // Scheme-relative (//host/path) and cross-origin URLs stay external;
+        // same-scheme references like "https:./file.png" resolve against the
+        // deployment like the browser does on an HTTPS page.
+        if (reference.startsWith('//')) {
+            continue;
+        }
+        let effectiveReference = reference;
+        if (schemeSeparated !== null && schemeSeparated[1] !== undefined) {
+            const scheme = schemeSeparated[1].toLowerCase();
+            if (scheme === 'https' || scheme === 'http') {
+                const afterScheme = reference.slice(schemeSeparated[1].length + 1);
+                if (afterScheme.startsWith('//')) {
+                    continue;
+                }
+                effectiveReference = afterScheme;
+            }
+            else {
+                continue;
+            }
+        }
+        const withoutQuery = effectiveReference.split(/[?#]/u)[0] ?? effectiveReference;
+        if (withoutQuery.length === 0) {
+            continue;
+        }
+        let normalized = posix.normalize(withoutQuery.startsWith('/') ? withoutQuery.slice(1) : `./${withoutQuery}`);
+        normalized = normalized.split('\\').join('/');
+        try {
+            normalized = normalized
+                .split('/')
+                .map((segment) => decodeURIComponent(segment))
+                .join('/');
+        }
+        catch {
+            throw new Error(`The deployment index.html references a malformed percent-encoded URL: ${reference}`);
+        }
+        if (normalized.startsWith('../') || normalized === '..' || posix.isAbsolute(normalized)) {
+            throw new Error(`The deployment index.html references a path outside the artifact root: ${reference}`);
+        }
+        // Track the concrete directory request URL before resolving it to the
+        // index document, so redirect protection sees the URL browsers request.
+        if (normalized.endsWith('/')) {
+            referencedDirectoryUrls.add(`/${normalized.slice(0, -1)}/`);
+        }
+        else if (normalized === '.') {
+            referencedDirectoryUrls.add('/');
+        }
+        // Directory URLs resolve to their index document, matching how Pages
+        // serves '/' and '/legal/' from index.html files.
+        if (normalized === '.' || normalized.endsWith('/')) {
+            normalized = `${normalized === '.' ? '' : normalized}index.html`;
+        }
+        if (stylesheetHrefs.has(rawReference)) {
+            activeStylesheets.add(normalized);
+        }
+        referenced.add(normalized);
+    }
+    // Stylesheet links (and the @import chain they start) carry their own
+    // url()/@import targets, resolved relative to each stylesheet's directory.
+    // Comments are stripped first, external URLs are skipped, root-relative
+    // targets resolve from the deployment root, percent-encoded segments
+    // decode, escaping targets are rejected, and chained imports follow with a
+    // visited set so circular imports cannot loop forever.
+    const visitedStylesheets = new Set();
+    const stylesheetQueue = [...activeStylesheets];
+    while (stylesheetQueue.length > 0) {
+        const stylesheet = stylesheetQueue.shift();
+        if (stylesheet === undefined || visitedStylesheets.has(stylesheet)) {
+            continue;
+        }
+        visitedStylesheets.add(stylesheet);
+        const { cssUrls, cssImports } = extractStylesheetTargets(readFileSync(join(deploymentRoot, stylesheet), 'utf8'));
+        const cssDir = stylesheet.includes('/')
+            ? `./${stylesheet.slice(0, stylesheet.lastIndexOf('/'))}`
+            : '.';
+        const resolvedUrls = [];
+        const resolvedImports = [];
+        const collectCssTarget = (rawTarget, sink) => {
+            const raw = decodeCssEscapes(rawTarget.trim());
+            if (raw.length === 0 || raw.startsWith('data:') || raw.startsWith('#')) {
+                return;
+            }
+            const scheme = /^([a-z][a-z0-9+.-]*):/iu.exec(raw);
+            if (scheme !== null
+                && scheme[1] !== undefined
+                && scheme[1].toLowerCase() !== 'https'
+                && scheme[1].toLowerCase() !== 'http') {
+                return;
+            }
+            const schemeText = scheme?.[1] ?? '';
+            let cssPath = scheme !== null ? raw.slice(schemeText.length + 1) : raw;
+            // Cross-scheme authority URLs (https://host/x, http:/host/x) are
+            // external; only same-scheme relative forms like https:./file.png
+            // resolve against the deployment.
+            if (scheme !== null && cssPath.startsWith('/')) {
+                return;
+            }
+            // Scheme-relative URLs without a scheme token (//host/x) are external.
+            if (scheme === null && cssPath.startsWith('//')) {
+                return;
+            }
+            cssPath = cssPath.split('?')[0]?.split('#')[0] ?? cssPath;
+            const cssTarget = cssPath.startsWith('/') ? cssPath.slice(1) : `${cssDir}/${cssPath}`;
+            const resolved = posix.normalize(cssTarget);
+            if (resolved.startsWith('../') || resolved === '..' || posix.isAbsolute(resolved)) {
+                throw new Error(`The stylesheet ${stylesheet} references a path outside the artifact root: ${raw}`);
+            }
+            sink.push(decodeReferenceSegments(resolved, `stylesheet ${stylesheet}`));
+        };
+        for (const cssUrl of cssUrls) {
+            collectCssTarget(cssUrl, resolvedUrls);
+        }
+        for (const cssImport of cssImports) {
+            collectCssTarget(cssImport, resolvedImports);
+        }
+        for (const resolvedUrl of resolvedUrls) {
+            referenced.add(resolvedUrl);
+        }
+        for (const resolvedImport of resolvedImports) {
+            referenced.add(resolvedImport);
+            // Imports are stylesheets by syntax whatever their URL looks like, and
+            // deduplication against earlier references must not suppress
+            // traversal: the browser still applies the imported file as CSS.
+            if (deploymentPaths.has(resolvedImport)
+                && !visitedStylesheets.has(resolvedImport)
+                && !stylesheetQueue.includes(resolvedImport)) {
+                stylesheetQueue.push(resolvedImport);
+            }
+        }
+    }
+    for (const reference of [...referenced].sort()) {
+        if (pagesControlArtifactNames.has(reference)) {
+            throw new Error(`The deployment index.html references the Pages control file ${reference}; `
+                + 'control artifacts are consumed by the host, not served to browsers.');
+        }
+        if (!deploymentPaths.has(reference)) {
+            throw new Error(`The deployment index.html references a missing file: ${reference} `
+                + `(resolved under ${deploymentRoot}).`);
+        }
+    }
+    // Declared legal pages are deployment-promised documents; their local
+    // references resolve against the page's own directory.
+    for (const page of declaredLegalPages(deploymentRoot)) {
+        const rawPageHtml = readFileSync(join(deploymentRoot, page), 'utf8');
+        const pageStyleReferences = [];
+        const pageCssSource = stripScriptsAndComments(rawPageHtml);
+        for (const styleBody of pageCssSource.matchAll(/<style\b(?:(?:"[^"]*"|'[^']*'|[^>"])*)>([\s\S]*?)<\/style\s*>/giu)) {
+            collectInlineCssReferences(styleBody[1] ?? '', pageStyleReferences);
+        }
+        for (const cssReference of pageStyleReferences) {
+            assertLocalReferenceResolves(cssReference, page.slice(0, -'index.html'.length), deploymentPaths, page);
+        }
+        const strippedPageHtml = stripNonMarkupRanges(rawPageHtml);
+        if (/<base\b/iu.test(strippedPageHtml)) {
+            throw new Error(`The legal page ${page} declares a base element; reference resolution `
+                + 'against a legal-page base is unsupported by this verifier.');
+        }
+        const metaTagPattern = /<meta\b(?:(?:"[^"]*"|'[^']*'|[^>"]))*>/giu;
+        for (const meta of rawPageHtml.matchAll(metaTagPattern)) {
+            const metaTag = meta[0] ?? '';
+            if (!/http-equiv\s*=\s*["']?refresh/iu.test(metaTag)) {
+                continue;
+            }
+            const content = metaTag.match(/content\s*=\s*(?:"([^"]*)"|'([^']*)')/iu);
+            if (content === null) {
+                continue;
+            }
+            const decodedContent = decodeHtmlReferences(content[1] ?? '');
+            const target = /^[^;,]*[,;]\s*url\s*=\s*(?:"([^"]+)"|'([^']+)'|([^;,\s]+))/iu.exec(decodedContent);
+            if (target !== null) {
+                assertLocalReferenceResolves(target[1] ?? target[2] ?? target[3] ?? '', page.slice(0, -'index.html'.length), deploymentPaths, page);
+            }
+        }
+        const pageHtml = strippedPageHtml;
+        for (const tag of pageHtml.matchAll(/<([A-Za-z][^\s/>]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/gu)) {
+            const tagName = (tag[1] ?? '').toLowerCase();
+            const attributes = tag[2] ?? '';
+            const resourceNames = tagName === 'object'
+                ? ['href', 'src', 'poster', 'data']
+                : ['href', 'src', 'poster', 'xlink:href'];
+            for (const attribute of attributes.matchAll(/([A-Za-z_:][-A-Za-z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gu)) {
+                const name = (attribute[1] ?? '').toLowerCase();
+                const value = attribute[2] ?? attribute[3] ?? attribute[4] ?? '';
+                if (name === 'style') {
+                    const pageCssReferences = [];
+                    collectInlineCssReferences(decodeHtmlReferences(value), pageCssReferences);
+                    for (const cssReference of pageCssReferences) {
+                        assertLocalReferenceResolves(cssReference, page.slice(0, -'index.html'.length), deploymentPaths, page);
+                    }
+                    continue;
+                }
+                if (!resourceNames.includes(name) && name !== 'srcset' && name !== 'srcdoc') {
+                    continue;
+                }
+                if (name === 'srcdoc' && value.length > 0) {
+                    const embeddedReferences = [];
+                    collectEmbeddedDocumentReferences(decodeHtmlReferences(value), embeddedReferences);
+                    for (const embeddedReference of embeddedReferences) {
+                        assertLocalReferenceResolves(embeddedReference, page.slice(0, -'index.html'.length), deploymentPaths, page);
+                    }
+                    continue;
+                }
+                if (name === 'srcset') {
+                    const candidates = [];
+                    pushSrcsetCandidates(decodeHtmlReferences(value), candidates);
+                    for (const candidate of candidates) {
+                        assertLocalReferenceResolves(candidate, page.slice(0, -'index.html'.length), deploymentPaths, page);
+                    }
+                    continue;
+                }
+                if (value.length === 0) {
+                    continue;
+                }
+                assertLocalReferenceResolves(value, page.slice(0, -'index.html'.length), deploymentPaths, page);
+            }
+        }
+    }
+    return [...referencedDirectoryUrls];
+}
+/**
+ * Decode attribute values with standards-compliant HTML semantics using the
+ * package's existing entities dependency (named references, numeric
+ * references, and U+FFFD replacement for invalid code points).
+ */
+function decodeHtmlReferences(text) {
+    return decodeHTMLAttribute(text);
+}
+/** List the deployment's declared legal page index files. */
+function declaredLegalPages(deploymentRoot) {
+    const manifestPath = join(deploymentRoot, 'legal-site.json');
+    if (!existsSync(manifestPath)) {
+        return [];
+    }
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (typeof parsed !== 'object'
+        || parsed === null
+        || !Array.isArray(parsed.pages)) {
+        return [];
+    }
+    return parsed.pages
+        .filter((page) => typeof page.path === 'string')
+        .map((page) => `${page.path.slice(1)}index.html`);
+}
+/** Resolve a legal-page reference against its directory and require the file. */
+function assertLocalReferenceResolves(reference, pageDirectory, deploymentPaths, page) {
+    const decoded = decodeHtmlReferences(reference).trim();
+    const schemeSeparated = /^([a-z][a-z0-9+.-]*):/iu.exec(decoded);
+    if (decoded.length === 0 || decoded.startsWith('#') || decoded.startsWith('data:')) {
+        return;
+    }
+    if (decoded.startsWith('//')) {
+        return;
+    }
+    let effective = decoded;
+    if (schemeSeparated !== null && schemeSeparated[1] !== undefined) {
+        const scheme = schemeSeparated[1].toLowerCase();
+        if (scheme === 'https' || scheme === 'http') {
+            const afterScheme = decoded.slice(schemeSeparated[1].length + 1);
+            if (afterScheme.startsWith('//')) {
+                return;
+            }
+            effective = afterScheme;
+        }
+        else {
+            return;
+        }
+    }
+    let withoutQuery = effective.split(/[?#]/u)[0] ?? effective;
+    if (withoutQuery.length === 0) {
+        return;
+    }
+    withoutQuery = withoutQuery.split('\\').join('/');
+    try {
+        withoutQuery = withoutQuery
+            .split('/')
+            .map((segment) => decodeURIComponent(segment))
+            .join('/');
+    }
+    catch {
+        throw new Error(`The legal page ${page} references a malformed percent-encoded URL: ${reference}`);
+    }
+    const fromDirectory = pageDirectory.length > 0 ? `./${pageDirectory}` : '.';
+    let normalized = posix.normalize(withoutQuery.startsWith('/') ? withoutQuery.slice(1) : `${fromDirectory}/${withoutQuery}`);
+    if (normalized.endsWith('/') || normalized === '.') {
+        normalized = normalized === '.' ? 'index.html' : `${normalized}index.html`;
+    }
+    if (normalized.startsWith('../') || normalized === '..' || posix.isAbsolute(normalized)) {
+        throw new Error(`The legal page ${page} references a path outside the deployment root: ${reference}`);
+    }
+    if (pagesControlArtifactNames.has(normalized)) {
+        throw new Error(`The legal page ${page} references the Pages control file ${normalized}; `
+            + 'control artifacts are consumed by the host, not served to browsers.');
+    }
+    if (!deploymentPaths.has(normalized)) {
+        throw new Error(`The legal page ${page} references a missing file: ${reference} `
+            + `(resolved to ${normalized}).`);
+    }
+}
+/** Apply the full resource scanner to an embedded srcdoc document. */
+function collectEmbeddedDocumentReferences(document, references) {
+    // The caller decoded this document's own attribute once, matching the
+    // browser's per-attribute decoding; style blocks are collected before
+    // stripping so their CSS references survive.
+    for (const styleBody of document.matchAll(/<style\b(?:(?:"[^"]*"|'[^']*'|[^>"])*)>([\s\S]*?)<\/style\s*>/giu)) {
+        collectInlineCssReferences(styleBody[1] ?? '', references);
+    }
+    const stripped = stripNonMarkupRanges(document);
+    for (const tag of stripped.matchAll(/<([A-Za-z][^\s/>]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/gu)) {
+        const tagName = (tag[1] ?? '').toLowerCase();
+        const attributes = tag[2] ?? '';
+        const resourceNames = tagName === 'object'
+            ? ['href', 'src', 'poster', 'data']
+            : ['href', 'src', 'poster', 'xlink:href'];
+        let embeddedMetaRefresh = false;
+        let embeddedMetaContent;
+        for (const attribute of attributes.matchAll(/([A-Za-z_:][-A-Za-z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gu)) {
+            const name = (attribute[1] ?? '').toLowerCase();
+            const value = attribute[2] ?? attribute[3] ?? attribute[4] ?? '';
+            if (tagName === 'meta' && name === 'http-equiv') {
+                embeddedMetaRefresh = value.trim().toLowerCase() === 'refresh';
+            }
+            if (tagName === 'meta' && name === 'content') {
+                embeddedMetaContent = value;
+            }
+            if (name === 'style') {
+                collectInlineCssReferences(decodeHtmlReferences(value), references);
+                continue;
+            }
+            if (svgUrlAttributeNames.has(name) && value.includes('url(')) {
+                collectInlineCssReferences(decodeHtmlReferences(value), references);
+                continue;
+            }
+            if (!resourceNames.includes(name) && name !== 'srcset' && name !== 'srcdoc') {
+                continue;
+            }
+            if (name === 'srcdoc' && value.length > 0) {
+                collectEmbeddedDocumentReferences(decodeHtmlReferences(value), references);
+                continue;
+            }
+            if (name !== 'srcset' && value.length > 0) {
+                references.push(value);
+            }
+        }
+        if (embeddedMetaRefresh && embeddedMetaContent !== undefined) {
+            const decodedContent = decodeHtmlReferences(embeddedMetaContent);
+            const target = /^[^;,]*[,;]\s*url\s*=\s*(?:"([^"]+)"|'([^']+)'|([^;,\s]+))/iu.exec(decodedContent);
+            if (target !== null) {
+                references.push(target[1] ?? target[2] ?? target[3] ?? '');
+            }
+        }
+        const srcset = attributes.match(/(?:^|\s)srcset\s*=\s*(?:"([^"]+)"|'([^']+)'|([^\s>]+))/iu);
+        if (srcset !== null) {
+            const rawCandidates = srcset[1] ?? srcset[2] ?? srcset[3] ?? '';
+            pushSrcsetCandidates(decodeHtmlReferences(rawCandidates), references);
+        }
+    }
+}
+/** Tokenize srcset candidates into the reference list. */
+/** Whether a link rel token list applies the target as a stylesheet. */
+function isStylesheetRel(rel) {
+    return rel !== undefined && rel.split(/\s+/u).includes('stylesheet');
+}
+/**
+ * Extract live url() targets and @import targets from a stylesheet with a
+ * small string-aware tokenizer:
+ *
+ * - comments are skipped;
+ * - url()/@import text inside quoted strings is inert content, so a
+ *   `content: "url(./missing.png)"` rule never becomes a reference;
+ * - @import is honored only before the first top-level style block, because
+ *   CSS parsing makes later imports inert;
+ * - @import supports both quoted-string and url() forms.
+ */
+function extractStylesheetTargets(css) {
+    const cssUrls = [];
+    const cssImports = [];
+    let index = 0;
+    let sawTopLevelBlock = false;
+    const skipString = () => {
+        const quote = css[index] ?? '';
+        index += 1;
+        while (index < css.length) {
+            const inner = css[index] ?? '';
+            index += 1;
+            if (inner === '\\') {
+                index += 1;
+                continue;
+            }
+            if (inner === quote) {
+                return;
+            }
+        }
+    };
+    while (index < css.length) {
+        const char = css[index] ?? '';
+        if (char === '"' || char === "'") {
+            skipString();
+            continue;
+        }
+        if (char === '/' && (css[index + 1] ?? '') === '*') {
+            const end = css.indexOf('*/', index + 2);
+            index = end === -1 ? css.length : end + 2;
+            continue;
+        }
+        if (char === '{') {
+            sawTopLevelBlock = true;
+            index += 1;
+            continue;
+        }
+        const rest = css.slice(index);
+        const urlMatch = /^url\(/iu.exec(rest);
+        if (urlMatch !== null) {
+            index += urlMatch[0].length;
+            let quote = '';
+            let argument = '';
+            while (index < css.length) {
+                const inner = css[index] ?? '';
+                if (quote === '' && (inner === '"' || inner === "'")) {
+                    quote = inner;
+                    index += 1;
+                    continue;
+                }
+                if (quote !== '' && inner === quote) {
+                    quote = '';
+                    index += 1;
+                    continue;
+                }
+                if (quote !== '' && inner === '\\') {
+                    argument += inner + (css[index + 1] ?? '');
+                    index += 2;
+                    continue;
+                }
+                if (quote === '' && inner === ')') {
+                    index += 1;
+                    break;
+                }
+                argument += inner;
+                index += 1;
+            }
+            cssUrls.push(argument.trim());
+            continue;
+        }
+        const importMatch = !sawTopLevelBlock ? /^@import\b/iu.exec(rest) : null;
+        if (importMatch !== null) {
+            index += importMatch[0].length;
+            let captured = '';
+            while (index < css.length) {
+                const inner = css[index] ?? '';
+                if (inner === ';') {
+                    index += 1;
+                    break;
+                }
+                captured += inner;
+                index += 1;
+            }
+            const trimmed = captured.trim();
+            const quotedForm = /^(['"])([\s\S]*)\1$/u.exec(trimmed);
+            if (quotedForm !== null) {
+                cssImports.push((quotedForm[2] ?? '').trim());
+            }
+            else {
+                const urlForm = /^url\(\s*(['"]?)([^'")]*)\1\s*\)$/iu.exec(trimmed);
+                if (urlForm !== null) {
+                    cssImports.push((urlForm[2] ?? '').trim());
+                }
+            }
+            continue;
+        }
+        index += 1;
+    }
+    return { cssUrls, cssImports };
+}
+/** Decode CSS string escapes (backslash-character and hex forms) like browsers do. */
+function decodeCssEscapes(value) {
+    if (!value.includes('\\')) {
+        return value;
+    }
+    return value.replace(/\\(?:([0-9a-fA-F]{1,6})\s?|(.))/gu, (_match, hex, plain) => {
+        if (hex === undefined) {
+            return plain ?? '';
+        }
+        const codePoint = Number.parseInt(hex, 16);
+        return codePoint > 1114111 || Number.isNaN(codePoint)
+            ? '\uFFFD'
+            : String.fromCodePoint(codePoint);
+    });
+}
+/** Percent-decode each path segment, mirroring the HTML reference handling. */
+function decodeReferenceSegments(path, label) {
+    try {
+        return path
+            .split('/')
+            .map((segment) => decodeURIComponent(segment))
+            .join('/');
+    }
+    catch {
+        throw new Error(`${label} references a malformed percent-encoded URL: ${path}`);
+    }
+}
+function pushSrcsetCandidates(candidates, references) {
+    let holdingUrl = false;
+    for (const token of candidates.split(/\s+/u)) {
+        for (const piece of token.split(/(?<=\d[xw]),/u)) {
+            const trimmed = piece.replace(/^[,]+|[,]+$/gu, '');
+            if (trimmed.length === 0) {
+                continue;
+            }
+            const isDescriptor = /^[\d.]+[wx]?$/u.test(trimmed);
+            if (holdingUrl && isDescriptor) {
+                continue;
+            }
+            references.push(trimmed);
+            const endedCandidate = /,$/u.test(piece);
+            holdingUrl = !isDescriptor && !endedCandidate;
+        }
+        if (/^[\d.]+[wx],?$/u.test(token)) {
+            holdingUrl = false;
+        }
+    }
+}
+/** Collect local url() and @import targets from inline CSS. */
+function collectInlineCssReferences(html, references) {
+    for (const match of html.matchAll(/url\(\s*(['"]?)([^'")]+)\1\s*\)/giu)) {
+        references.push(match[2] ?? '');
+    }
+    for (const match of html.matchAll(/@import\s+(['"])([^'"]+)\1/giu)) {
+        references.push(match[2] ?? '');
+    }
+}
+/** Drop comments, script bodies, and style bodies from HTML before scanning. */
+/** Strip scripts and HTML comments while keeping style blocks intact. */
+function stripScriptsAndComments(html) {
+    return html
+        .replace(/<!--[\s\S]*?-->/gu, '')
+        .replace(/<script\b((?:"[^"]*"|'[^']*'|[^>"'])*)>[\s\S]*?<\/script\s*>/giu, '')
+        .replace(/<template\b(?:(?:"[^"]*"|'[^']*'|[^>"]))*>[\s\S]*?<\/template\s*>/giu, '');
+}
+function stripNonMarkupRanges(html) {
+    return html
+        .replace(/<!--[\s\S]*?-->/gu, '')
+        .replace(/<script\b((?:"[^"]*"|'[^']*'|[^>"'])*)>[\s\S]*?<\/script\s*>/giu, '<script$1></script>')
+        .replace(/<textarea\b[^>]*>[\s\S]*?<\/textarea\s*>/giu, '<textarea></textarea>')
+        .replace(/<template\b(?:(?:"[^"]*"|'[^']*'|[^>"]))*>[\s\S]*?<\/template\s*>/giu, '<template></template>')
+        .replace(/<title\b[^>]*>[\s\S]*?<\/title\s*>/giu, '<title></title>')
+        .replace(/<style\b((?:"[^"]*"|'[^']*'|[^>"'])*)>[\s\S]*?<\/style\s*>/giu, '<style$1></style>');
+}
+function verifyCloudflarePagesRoutes(deploymentRoot, profile) {
+    const routesPath = `${deploymentRoot}/_routes.json`;
+    if (!existsSync(routesPath)) {
+        throw new Error('The deployment is missing _routes.json.');
+    }
+    const routes = JSON.parse(readFileSync(routesPath, 'utf8'));
+    if (typeof routes !== 'object' || routes === null) {
+        throw new Error('The deployment _routes.json must be an object.');
+    }
+    const record = routes;
+    const include = record.include;
+    const exclude = record.exclude;
+    if (record.version !== 1 || !Array.isArray(include) || !Array.isArray(exclude)) {
+        throw new Error('The deployment _routes.json must declare version 1 with include and exclude arrays.');
+    }
+    const expectedInclude = profile === 'api-canonical-index'
+        ? ['/api/*', '/index.html']
+        : ['/api/*'];
+    const actual = {
+        version: 1,
+        include: [...include],
+        exclude: [...exclude],
+    };
+    const expected = {
+        version: 1,
+        include: expectedInclude,
+        exclude: [],
+    };
+    if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+        throw new Error(`The deployment _routes.json does not match the reviewed ${profile} profile. `
+            + `Expected ${JSON.stringify(expected)} but found ${JSON.stringify(actual)}. `
+            + 'Broader worker routes are rejected because they silently bypass the '
+            + 'static PWA serving this verification guarantees.');
+    }
+    return {
+        include: actual.include.map(String),
+        exclude: actual.exclude.map(String),
+    };
+}
+function assertNoSourceRoutesShadowed(routes, sourceFiles, profile) {
+    // The api-canonical-index profile deliberately routes /index.html through
+    // the worker, whose reviewed handler serves the canonical index bytes from
+    // the deployment assets; every other route collision is a real shadowing.
+    const shadowingRoutes = routes.include.filter((route) => !(profile === 'api-canonical-index' && route === '/index.html'));
+    for (const file of sourceFiles) {
+        const requestPath = `/${file.path}`;
+        for (const route of shadowingRoutes) {
+            if (cloudflarePagesPathMatches(route, requestPath)) {
+                throw new Error(`The source artifact file ${file.path} is served at ${requestPath}, which the `
+                    + `Pages worker route ${route} intercepts; the reviewed profiles route /api/* `
+                    + 'through the worker, so precached files must not live under those paths.');
+            }
+        }
+    }
+}
+/** Declared legal pages must be served statically, not intercepted by the worker. */
+function assertNoLegalRoutesShadowed(routes, legalPages, profile) {
+    for (const page of legalPages) {
+        const requestPath = `/${page.slice(0, -'index.html'.length)}`;
+        for (const route of routes.include) {
+            if (cloudflarePagesPathMatches(route, requestPath)
+                && !(profile === 'api-canonical-index' && route === '/index.html')) {
+                throw new Error(`The declared legal page ${page} is served at ${requestPath}, which the `
+                    + `Pages worker route ${route} intercepts instead of serving the file.`);
+            }
+        }
+    }
+}
+function verifyCloudflarePagesHeaders(deploymentRoot, sourceFiles, deploymentFiles, declaredLegalDirectories, workerRoutes) {
+    const headersPath = `${deploymentRoot}/_headers`;
+    if (!existsSync(headersPath)) {
+        throw new Error('The deployment is missing _headers.');
+    }
+    const blocks = parseCloudflarePagesHeaders(readFileSync(headersPath, 'utf8'));
+    const sourcePaths = new Set(sourceFiles.map((file) => file.path));
+    const deploymentPaths = new Set(deploymentFiles.map((file) => file.path));
+    const requirements = [];
+    // Host-owned legal content must stay fresh: the deployment declares the
+    // pages and ships legal-site.json, and stale privacy or terms pages after
+    // an update are a compliance problem, so they carry revalidation policy.
+    for (const file of deploymentFiles) {
+        if (file.path === 'legal-site.json') {
+            requirements.push({
+                requestPath: '/legal-site.json',
+                expected: freshCacheControl,
+                label: 'legal-site.json',
+            });
+        }
+        const declaredLegalPage = file.path.endsWith('/index.html')
+            && file.path.includes('/')
+            && declaredLegalDirectories.has(`${file.path.slice(0, -'index.html'.length - 1)}/`);
+        if ((declaredLegalPage || (!sourcePaths.has(file.path) && file.path.includes('/')))
+            && file.path.endsWith('/index.html')) {
+            const directoryUrl = `/${file.path.slice(0, -'index.html'.length)}`;
+            requirements.push({
+                requestPath: directoryUrl,
+                expected: freshCacheControl,
+                label: `${file.path} directory URL`,
+            });
+            requirements.push({
+                requestPath: `/${file.path}`,
+                expected: freshCacheControl,
+                label: `${file.path} index URL`,
+            });
+        }
+    }
+    if (sourcePaths.has('index.html')) {
+        // Under api-canonical-index the worker serves /index.html and Pages
+        // _headers rules do not apply to function responses, so the index.html
+        // policy is only certifiable for the statically served root path.
+        requirements.push({ requestPath: '/', expected: freshCacheControl, label: 'the PWA root' });
+        if (workerRoutes.include.includes('/index.html')) {
+            requirements.push({
+                requestPath: '/index.html',
+                expected: freshCacheControl,
+                label: 'index.html (worker-served; static _headers policy not certified)',
+                skip: true,
+            });
+        }
+        else {
+            requirements.push({
+                requestPath: '/index.html',
+                expected: freshCacheControl,
+                label: 'index.html',
+            });
+        }
+    }
+    for (const file of [...freshCacheControlFiles, ...noStoreCacheControlFiles]) {
+        if (sourcePaths.has(file.slice(1))) {
+            requirements.push({
+                requestPath: file,
+                expected: noStoreCacheControlFiles.has(file)
+                    ? noStoreCacheControl
+                    : freshCacheControl,
+                label: file.slice(1),
+            });
+        }
+    }
+    // Directory-scoped policies are evaluated against every actual file path so
+    // placeholder-shaped blocks that do not cover the real URLs cannot satisfy
+    // the requirement by coincidence. Only filenames that carry a content
+    // hash may be cached immutably; stable names require revalidation so a
+    // later release at the same URL is served fresh.
+    for (const file of sourceFiles) {
+        const directory = file.path.includes('/') ? (file.path.split('/')[0] ?? '') : '';
+        if (directory.length === 0) {
+            continue;
+        }
+        if (immutableCacheControlDirectories.has(directory)) {
+            // Filename-based hash detection cannot distinguish hashes from words
+            // after six review rounds of counterexamples, so the contract is now
+            // explicit-policy: every asset URL must carry a deliberate caching
+            // strategy — immutable for hashed pipelines, revalidation for stable
+            // names — and only a missing or conflicting policy fails.
+            requirements.push({
+                requestPath: `/${file.path}`,
+                expected: immutableCacheControl,
+                alsoAccepts: freshCacheControl,
+                label: `asset ${file.path}`,
+            });
+        }
+        else if (noStoreCacheControlDirectories.has(directory)) {
+            requirements.push({
+                requestPath: `/${file.path}`,
+                expected: noStoreCacheControl,
+                label: `stable-name ${file.path}`,
+            });
+        }
+    }
+    for (const requirement of requirements) {
+        if (requirement.skip === true) {
+            continue;
+        }
+        const effective = evaluateCloudflarePagesHeader(blocks, requirement.requestPath, 'Cache-Control');
+        if (effective.additions.length > 1) {
+            throw new Error(`Conflicting Cloudflare Pages cache policy for ${requirement.label}: `
+                + `${requirement.requestPath} receives comma-joined Cache-Control values `
+                + `(${effective.additions.join(', ')}) because more than one matching block `
+                + 'adds the header. Cloudflare joins duplicate headers with commas instead '
+                + 'of overriding them.');
+        }
+        if (effective.value === undefined) {
+            throw new Error(`Cloudflare Pages cache policy for ${requirement.label} is missing: no matching `
+                + `block sets Cache-Control to ${requirement.expected} for `
+                + `${requirement.requestPath}`
+                + (effective.removed
+                    ? ' (a matching block removed the header with a removal directive)'
+                    : '')
+                + '.');
+        }
+        const acceptedValues = [requirement.expected, requirement.alsoAccepts]
+            .filter((value) => value !== undefined)
+            .map(normalizeHeaderDirectiveValue);
+        if (!acceptedValues.includes(normalizeHeaderDirectiveValue(effective.value))) {
+            throw new Error(`Cloudflare Pages cache policy for ${requirement.label} is wrong: expected `
+                + `${requirement.expected}${requirement.alsoAccepts === undefined ? '' : ` or ${requirement.alsoAccepts}`} `
+                + `for ${requirement.requestPath} but the effective value is ${effective.value}.`);
+        }
+    }
+}
+/** Whether a filename carries a Vite-style content hash segment. */
+function carriesContentHash(portablePath) {
+    const name = portablePath.split('/').pop() ?? '';
+    // Only unambiguous hexadecimal segments earn the immutable policy. Vite's
+    // URL-safe base64 segments cannot be told apart from mixed-case words like
+    // "Player2D" lexically, so they take the fail-safe revalidation policy:
+    // a misclassified hash merely revalidates, while a misclassified stable
+    // name would serve stale release bytes for a year.
+    return /(^|[/.-])[0-9a-f]{8,}\.[a-z0-9]+$/iu.test(name);
+}
+function verifyCloudflarePagesRedirects(deploymentRoot, sourceFiles, deploymentLegalPaths, referencedDirectoryUrls) {
+    const redirectsPath = `${deploymentRoot}/_redirects`;
+    if (!existsSync(redirectsPath)) {
+        throw new Error('The deployment is missing _redirects.');
+    }
+    const rules = parseCloudflarePagesRedirects(readFileSync(redirectsPath, 'utf8'));
+    const protectedPaths = [
+        ...protectedPwaMetadataRequestPaths,
+        ...sourceFiles.map((file) => `/${file.path}`),
+        ...deploymentLegalPaths,
+        ...referencedDirectoryUrls,
+    ];
+    for (const rule of rules) {
+        for (const protectedPath of protectedPaths) {
+            if (cloudflarePagesPathMatches(rule.source, protectedPath)) {
+                throw new Error(`The deployment _redirects rule ${rule.source} covers the protected PWA path `
+                    + `${protectedPath} and moves it to ${rule.destination}; the game root and `
+                    + 'PWA-critical files must be served directly.');
+            }
+        }
+    }
+}