feat: prerender crawlable portfolio artifacts
This commit is contained in:
293
scripts/verify-artifacts.mjs
Normal file
293
scripts/verify-artifacts.mjs
Normal file
@@ -0,0 +1,293 @@
|
||||
import { createHash } from 'node:crypto';
|
||||
import { lstat, readFile, readdir } from 'node:fs/promises';
|
||||
import { dirname, relative, resolve, sep } from 'node:path';
|
||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||||
import { loadProductionInputs } from '../src/content/load-production-inputs.ts';
|
||||
import { parseExactConfigArgument } from './prerender.mjs';
|
||||
|
||||
const scriptPath = fileURLToPath(import.meta.url);
|
||||
const repositoryRoot = resolve(dirname(scriptPath), '..');
|
||||
const canonicalSectionIds = [
|
||||
'start', 'profile', 'experience', 'infrastructure', 'selected-builds', 'additional-work', 'toolkit', 'contact',
|
||||
];
|
||||
const prohibitedSurfaces = [
|
||||
/__PORTFOLIO_INPUTS__/iu,
|
||||
/(?:evidenceId|sourcePath|sourceFingerprint|approvalOwner|privacyClassification|denylist|originalFilename)/iu,
|
||||
/sourceMappingURL/iu,
|
||||
];
|
||||
|
||||
const escapeRegularExpression = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
|
||||
const escapeHtml = (value) => value
|
||||
.replace(/&/gu, '&')
|
||||
.replace(/</gu, '<')
|
||||
.replace(/>/gu, '>')
|
||||
.replace(/"/gu, '"');
|
||||
|
||||
const readRequiredText = async (root, name) => {
|
||||
try {
|
||||
return await readFile(resolve(root, name), 'utf8');
|
||||
} catch (error) {
|
||||
if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
|
||||
throw new Error(`Missing required artifact: ${name}`);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
};
|
||||
|
||||
const listArtifacts = async (root) => {
|
||||
const rootStats = await lstat(root);
|
||||
if (rootStats.isSymbolicLink() || !rootStats.isDirectory()) {
|
||||
throw new Error('Artifact root must be a non-symlink directory.');
|
||||
}
|
||||
const files = [];
|
||||
for (const entry of await readdir(root, { withFileTypes: true })) {
|
||||
const entryPath = resolve(root, entry.name);
|
||||
if (entry.isSymbolicLink()) throw new Error(`Unexpected linked artifact: ${entry.name}`);
|
||||
if (entry.isDirectory()) {
|
||||
if (entry.name !== 'assets') throw new Error(`Unexpected artifact directory: ${entry.name}`);
|
||||
for (const asset of await readdir(entryPath, { withFileTypes: true })) {
|
||||
if (asset.isSymbolicLink() || !asset.isFile()) {
|
||||
throw new Error(`Unexpected linked or nested artifact: assets/${asset.name}`);
|
||||
}
|
||||
files.push(`assets/${asset.name}`);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (!entry.isFile()) throw new Error(`Unexpected special artifact: ${entry.name}`);
|
||||
files.push(entry.name);
|
||||
}
|
||||
return files.sort();
|
||||
};
|
||||
|
||||
const assertArtifactInventory = (files, html, inputs) => {
|
||||
const expectedRootFiles = new Set(['index.html', 'robots.txt', '_headers.example', '_redirects.example']);
|
||||
if (inputs.site.environment === 'production') expectedRootFiles.add('sitemap.xml');
|
||||
const referencedAssets = new Set(
|
||||
[...html.matchAll(/(?:src|href)="\/assets\/([a-zA-Z0-9._-]+)"/gu)].map((match) => `assets/${match[1]}`),
|
||||
);
|
||||
for (const asset of inputs.manifest.assets) referencedAssets.add(`assets/${asset.fileName}`);
|
||||
|
||||
for (const file of files) {
|
||||
if (file.endsWith('.map')) throw new Error(`Source map artifact is prohibited: ${file}`);
|
||||
if (file.startsWith('assets/')) {
|
||||
if (!referencedAssets.has(file)) throw new Error(`Unexpected artifact: ${file}`);
|
||||
} else if (!expectedRootFiles.has(file)) {
|
||||
if (inputs.site.environment === 'preview' && file === 'sitemap.xml') {
|
||||
throw new Error('Preview artifacts must not publish a sitemap.');
|
||||
}
|
||||
throw new Error(`Unexpected artifact: ${file}`);
|
||||
}
|
||||
}
|
||||
for (const required of [...expectedRootFiles, ...referencedAssets]) {
|
||||
if (!files.includes(required)) throw new Error(`Missing required artifact: ${required}`);
|
||||
}
|
||||
};
|
||||
|
||||
const assertNoProhibitedSurfaces = async (root, files) => {
|
||||
for (const file of files) {
|
||||
const bytes = await readFile(resolve(root, file));
|
||||
const text = bytes.toString('utf8');
|
||||
for (const pattern of prohibitedSurfaces) {
|
||||
if (pattern.test(text)) throw new Error(`Prohibited surface detected in ${file}.`);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
const exactlyOneMatch = (text, expression, label) => {
|
||||
const matches = [...text.matchAll(expression)];
|
||||
if (matches.length !== 1) throw new Error(`Expected exactly one ${label}.`);
|
||||
return matches[0];
|
||||
};
|
||||
|
||||
const assertSemanticHtml = (html, inputs) => {
|
||||
if (!/<html lang="en">/u.test(html)) throw new Error('Final HTML must declare lang=en.');
|
||||
const h1 = exactlyOneMatch(html, /<h1\b[^>]*>([\s\S]*?)<\/h1>/gu, 'H1');
|
||||
if (h1[1] !== escapeHtml(inputs.content.identity.name)) throw new Error('H1 identity does not match public content.');
|
||||
const adjacentIdentity = `<h1>${escapeHtml(inputs.content.identity.name)}</h1><p>${escapeHtml(inputs.content.identity.role)}</p>`;
|
||||
if (!html.includes(adjacentIdentity)) throw new Error('The canonical role must be immediately adjacent to the H1.');
|
||||
|
||||
for (const id of canonicalSectionIds) {
|
||||
const sectionMatches = html.match(new RegExp(`<section id="${escapeRegularExpression(id)}"(?:\\s|>)`, 'gu')) ?? [];
|
||||
if (sectionMatches.length !== 1) throw new Error(`Expected exactly one section: ${id}`);
|
||||
const navigationMatches = html.match(new RegExp(`href="#${escapeRegularExpression(id)}"`, 'gu')) ?? [];
|
||||
if (navigationMatches.length !== 1) throw new Error(`Expected one native navigation link for section: ${id}`);
|
||||
const label = inputs.content.navigation.find((item) => item.id === id)?.label;
|
||||
if (label === undefined || !html.includes(`<h2 id="${id}-heading">${escapeHtml(label.toUpperCase())}</h2>`)) {
|
||||
throw new Error(`Missing canonical section heading: ${id}`);
|
||||
}
|
||||
}
|
||||
|
||||
const requiredVisibleCopy = [
|
||||
inputs.content.systemsOperations.title,
|
||||
inputs.content.infrastructure.title,
|
||||
...inputs.content.infrastructure.bands.flatMap((band) => [band.title, band.summary]),
|
||||
...inputs.content.projects.selected.flatMap((project) => [project.title, project.summary]),
|
||||
...inputs.content.toolkit.flatMap((group) => [group.title, ...group.technologies.map((technology) => technology.name)]),
|
||||
inputs.content.contact.email,
|
||||
];
|
||||
for (const copy of requiredVisibleCopy) {
|
||||
if (!html.includes(escapeHtml(copy))) throw new Error(`Missing required semantic evidence: ${copy}`);
|
||||
}
|
||||
if (!html.includes(`href="mailto:${escapeHtml(inputs.content.contact.email)}"`)) {
|
||||
throw new Error('Missing visible mailto contact link.');
|
||||
}
|
||||
|
||||
const moduleScript = exactlyOneMatch(html, /<script type="module"[^>]*src="\/assets\/[a-zA-Z0-9._-]+\.js"[^>]*><\/script>/gu, 'client module script');
|
||||
const snapshot = exactlyOneMatch(
|
||||
html,
|
||||
/<script id="portfolio-inputs" type="application\/json">([\s\S]*?)<\/script>/gu,
|
||||
'inert input snapshot',
|
||||
);
|
||||
let parsedSnapshot;
|
||||
try {
|
||||
parsedSnapshot = JSON.parse(snapshot[1]);
|
||||
} catch {
|
||||
throw new Error('The inert input snapshot is malformed.');
|
||||
}
|
||||
if (JSON.stringify(parsedSnapshot) !== JSON.stringify(inputs)) {
|
||||
throw new Error('Hydration snapshot does not match the server input bytes and meaning.');
|
||||
}
|
||||
if (snapshot.index >= moduleScript.index || h1.index >= moduleScript.index) {
|
||||
throw new Error('Semantic HTML and inert snapshot must precede the client module script.');
|
||||
}
|
||||
};
|
||||
|
||||
const assertMetadata = (html, inputs) => {
|
||||
const expectedTitle = escapeHtml(inputs.content.metadata.title);
|
||||
const title = exactlyOneMatch(html, /<title>([\s\S]*?)<\/title>/gu, 'page title');
|
||||
if (title[1] !== expectedTitle) throw new Error('Page title does not match public content.');
|
||||
const canonical = exactlyOneMatch(html, /<link rel="canonical" href="([^"]+)" \/>/gu, 'canonical link');
|
||||
if (canonical[1] !== inputs.site.canonicalUrl) throw new Error('Canonical URL does not match site config.');
|
||||
const description = exactlyOneMatch(html, /<meta name="description" content="([^"]+)" \/>/gu, 'meta description');
|
||||
if (description[1] !== escapeHtml(inputs.content.metadata.description)) {
|
||||
throw new Error('Meta description does not match public content.');
|
||||
}
|
||||
for (const property of ['og:type', 'og:title', 'og:description', 'og:url']) {
|
||||
exactlyOneMatch(html, new RegExp(`<meta property="${property}" content="[^"]+" \\/>`, 'gu'), `${property} metadata`);
|
||||
}
|
||||
const ogImages = [...html.matchAll(/<meta property="og:image"/gu)];
|
||||
if (inputs.content.metadata.socialPreviewAssetId === undefined && ogImages.length !== 0) {
|
||||
throw new Error('Open Graph image must be omitted without an approved manifest asset.');
|
||||
}
|
||||
|
||||
const jsonLdMatch = exactlyOneMatch(
|
||||
html,
|
||||
/<script type="application\/ld\+json">([\s\S]*?)<\/script>/gu,
|
||||
'JSON-LD block',
|
||||
);
|
||||
let jsonLd;
|
||||
try {
|
||||
jsonLd = JSON.parse(jsonLdMatch[1]);
|
||||
} catch {
|
||||
throw new Error('JSON-LD is malformed.');
|
||||
}
|
||||
if (jsonLd['@type'] !== 'ProfilePage' || jsonLd.mainEntity?.['@type'] !== 'Person') {
|
||||
throw new Error('JSON-LD must contain one ProfilePage with one nested Person.');
|
||||
}
|
||||
const person = jsonLd.mainEntity;
|
||||
if (
|
||||
person.name !== inputs.content.identity.name ||
|
||||
person.jobTitle !== inputs.content.identity.role ||
|
||||
person.url !== inputs.site.canonicalUrl ||
|
||||
jsonLd.url !== inputs.site.canonicalUrl
|
||||
) {
|
||||
throw new Error('JSON-LD identity or canonical URL is inconsistent.');
|
||||
}
|
||||
const expectedSameAs = inputs.content.contact.social.map((link) => link.url);
|
||||
if (JSON.stringify(person.sameAs ?? []) !== JSON.stringify(expectedSameAs)) {
|
||||
throw new Error('JSON-LD sameAs contains an unverified or missing profile.');
|
||||
}
|
||||
if (jsonLdMatch[1].toLowerCase().includes('</script')) throw new Error('JSON-LD contains a script-closing hazard.');
|
||||
return jsonLdMatch[1];
|
||||
};
|
||||
|
||||
const assertSecurityHeaders = (headers, inputs, serializedJsonLd) => {
|
||||
const required = [
|
||||
"default-src 'self'", "script-src 'self'", "style-src 'self'", "img-src 'self'", "media-src 'self'",
|
||||
"font-src 'self'", "connect-src 'none'", "object-src 'none'", "base-uri 'none'", "frame-ancestors 'none'",
|
||||
"form-action 'none'", 'upgrade-insecure-requests', 'X-Content-Type-Options: nosniff',
|
||||
'Referrer-Policy: no-referrer', 'X-Frame-Options: DENY',
|
||||
'Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=(), accelerometer=(), gyroscope=(), magnetometer=()',
|
||||
];
|
||||
for (const value of required) {
|
||||
if (!headers.includes(value)) throw new Error(`Missing security header policy: ${value}`);
|
||||
}
|
||||
const expectedHash = `sha256-${createHash('sha256').update(serializedJsonLd).digest('base64')}`;
|
||||
const hashes = headers.match(/sha256-[A-Za-z0-9+/=]+/gu) ?? [];
|
||||
if (hashes.length !== 1 || hashes[0] !== expectedHash) {
|
||||
throw new Error('CSP hash does not match the actual JSON-LD bytes.');
|
||||
}
|
||||
if (inputs.site.environment === 'preview') {
|
||||
if (!headers.includes('Cache-Control: private, no-store') ||
|
||||
!headers.includes('X-Robots-Tag: noindex, nofollow, noarchive')) {
|
||||
throw new Error('Preview headers must be private and noindex.');
|
||||
}
|
||||
if (headers.includes('Strict-Transport-Security')) throw new Error('Preview headers must omit HSTS.');
|
||||
} else {
|
||||
if (!headers.includes('Strict-Transport-Security: max-age=31536000')) {
|
||||
throw new Error('Production headers must include HSTS.');
|
||||
}
|
||||
if (headers.includes('X-Robots-Tag') || headers.includes('private, no-store')) {
|
||||
throw new Error('Production headers must omit preview directives.');
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
const assertCrawlArtifacts = async (root, inputs, headers) => {
|
||||
const robots = await readRequiredText(root, 'robots.txt');
|
||||
const redirects = await readRequiredText(root, '_redirects.example');
|
||||
if (/https?:\/\//iu.test(redirects)) throw new Error('Redirect example must not invent a host.');
|
||||
if (inputs.site.environment === 'preview') {
|
||||
if (robots !== 'User-agent: *\nDisallow: /\n' || /sitemap/iu.test(robots)) {
|
||||
throw new Error('Preview robots must disallow crawling without advertising a sitemap.');
|
||||
}
|
||||
return;
|
||||
}
|
||||
const sitemapUrl = new URL('/sitemap.xml', inputs.site.canonicalUrl).href;
|
||||
if (robots !== `User-agent: *\nAllow: /\nSitemap: ${sitemapUrl}\n`) {
|
||||
throw new Error('Production robots policy must allow the canonical page and advertise its sitemap.');
|
||||
}
|
||||
const sitemap = await readRequiredText(root, 'sitemap.xml');
|
||||
if (!sitemap.includes(`<loc>${inputs.site.canonicalUrl}</loc>`)) {
|
||||
throw new Error('Production sitemap must contain the canonical site URL.');
|
||||
}
|
||||
if (!headers.includes('Cache-Control: public, max-age=0, must-revalidate')) {
|
||||
throw new Error('Production HTML requires revalidation caching.');
|
||||
}
|
||||
};
|
||||
|
||||
export const verifyArtifactDirectory = async (root, inputs) => {
|
||||
const html = await readRequiredText(root, 'index.html');
|
||||
const files = await listArtifacts(root);
|
||||
assertArtifactInventory(files, html, inputs);
|
||||
await assertNoProhibitedSurfaces(root, files);
|
||||
assertSemanticHtml(html, inputs);
|
||||
const serializedJsonLd = assertMetadata(html, inputs);
|
||||
const headers = await readRequiredText(root, '_headers.example');
|
||||
assertSecurityHeaders(headers, inputs, serializedJsonLd);
|
||||
await assertCrawlArtifacts(root, inputs, headers);
|
||||
};
|
||||
|
||||
const assertInsideRepository = (path) => {
|
||||
const pathRelativeToRoot = relative(repositoryRoot, path);
|
||||
if (pathRelativeToRoot === '..' || pathRelativeToRoot.startsWith(`..${sep}`)) {
|
||||
throw new Error('Verification input escaped the repository root.');
|
||||
}
|
||||
};
|
||||
|
||||
export const verifyArtifacts = async (configPath) => {
|
||||
const configAbsolutePath = resolve(repositoryRoot, configPath);
|
||||
assertInsideRepository(configAbsolutePath);
|
||||
const inputs = await loadProductionInputs({
|
||||
contentJson: pathToFileURL(resolve(repositoryRoot, 'content/public/portfolio-content.json')),
|
||||
assetManifestJson: pathToFileURL(resolve(repositoryRoot, 'content/public/asset-manifest.json')),
|
||||
preparedAssetRoot: pathToFileURL(`${resolve(repositoryRoot, 'inputs/prepared-assets')}${sep}`),
|
||||
siteConfigJson: pathToFileURL(configAbsolutePath),
|
||||
});
|
||||
await verifyArtifactDirectory(resolve(repositoryRoot, 'dist'), inputs);
|
||||
};
|
||||
|
||||
if (process.argv[1] !== undefined && resolve(process.argv[1]) === scriptPath) {
|
||||
const configPath = parseExactConfigArgument(process.argv.slice(2));
|
||||
await verifyArtifacts(configPath);
|
||||
}
|
||||
Reference in New Issue
Block a user