@stealthscale/sdk-host 0.1.0 → 0.4.0

package/dist/deploy.js

@@ -0,0 +1,254 @@
+import { t as DEPLOYMENT_ELEMENT } from "./document-CeEtZo2E.js";
+import { MANIFEST_FILE, RELEASE_FILE, lineOf, preloadsOf, releaseProblems, unmetRequirements } from "@stealthscale/sdk-core";
+//#region src/deploy.ts
+/**
+* Writes the parts of a product's document that depend on its deployment: the import map with the
+* integrity of every file of every release, the content security policy, the module preloads of
+* each release's manifest, and the deployment that the page reads.
+*
+* @remarks
+*   The module runs wherever the document is written: a deployment step in Node, or a server that
+*   renders the document. It reads each release's description over `fetch` and digests it with Web
+*   Crypto, so it imports no Node built-in.
+*/
+/**
+* The start tag of the import map that a product's build writes into its document.
+*/
+const IMPORT_MAP_START = "<script type=\"importmap\">";
+/**
+* The end tag of a `script` element.
+*/
+const SCRIPT_END = "<\/script>";
+/**
+* Fetches a URL with the process's `fetch`.
+*/
+const FETCHING = (url) => fetch(url);
+/**
+* Returns the integrity of some bytes, in the form `sha384-<base64>`.
+*/
+async function integrityOf(bytes) {
+	const digest = new Uint8Array(await crypto.subtle.digest("SHA-384", bytes));
+	return `sha384-${btoa(String.fromCodePoint(...digest))}`;
+}
+/**
+* Returns a value as JSON that a `script` element contains as written, with every `<` escaped.
+*/
+function scriptText(value) {
+	return JSON.stringify(value).replaceAll("<", String.raw`\u003c`);
+}
+/**
+* Returns a text escaped for an attribute value between double quotes. The function escapes every
+* `&`, `"` and `<`.
+*/
+function attributeText(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;");
+}
+/**
+* Reads a file of a release, and returns its bytes or the reason the step cannot use them.
+*/
+async function bytesOf(fetching, url) {
+	try {
+		const response = await fetching(url);
+		return response.ok ? await response.arrayBuffer() : `${url} responded with ${String(response.status)}.`;
+	} catch (error) {
+		return `${url} failed to load: ${String(error)}`;
+	}
+}
+/**
+* Returns a release with its description, or the reason the step leaves it out.
+*/
+async function listedOf(fetching, { base, integrity, options }) {
+	const url = new URL(RELEASE_FILE, base).href;
+	const bytes = await bytesOf(fetching, url);
+	let value;
+	if (typeof bytes === "string") return {
+		base,
+		detail: bytes
+	};
+	const digest = await integrityOf(bytes);
+	if (digest !== integrity) return {
+		base,
+		detail: `${url} has the digest ${digest}, and the deployment pins ${integrity}.`
+	};
+	try {
+		value = JSON.parse(new TextDecoder().decode(bytes));
+	} catch (error) {
+		return {
+			base,
+			detail: `${url} does not parse: ${String(error)}`
+		};
+	}
+	const problems = releaseProblems(value);
+	if (problems.length > 0) return {
+		base,
+		detail: problems.map((one) => lineOf(one)).join("; ")
+	};
+	const release = value;
+	return options === void 0 ? {
+		base,
+		integrity,
+		release
+	} : {
+		base,
+		integrity,
+		options,
+		release
+	};
+}
+/**
+* Returns the integrity of every file of every release, by the file's absolute URL.
+*/
+function integrityMapOf(listed) {
+	return Object.fromEntries(listed.flatMap(({ base, release }) => Object.entries(release.files).map(([path, integrity]) => [new URL(path, base).href, integrity])));
+}
+/**
+* Returns the modules of each provided specifier that a listed release imports, keyed by specifier.
+* Each list starts with the URL of the specifier's entry, followed by the URLs of the product's
+* chunks that the entry imports.
+*/
+function modulesOf(listed, provided) {
+	const modules = [...new Set(listed.flatMap(({ release }) => Object.values(release.imports).flat().filter((imported) => !Object.hasOwn(release.imports, imported))))].flatMap((specifier) => {
+		const entry = provided.imports[specifier];
+		return entry === void 0 ? [] : [[specifier, [entry, ...provided.chunks[specifier] ?? []]]];
+	});
+	return Object.fromEntries(modules.toSorted(([one], [two]) => one.localeCompare(two)));
+}
+/**
+* Returns the `link` element that preloads a module, as text.
+*/
+function moduleTagOf({ href, integrity }) {
+	const checked = integrity === void 0 ? "" : ` integrity="${attributeText(integrity)}"`;
+	return `<link rel="modulepreload" crossorigin href="${attributeText(href)}"${checked} />`;
+}
+/**
+* Returns the path of a release's catalogue in the page's language.
+*/
+function catalogueOf(provided) {
+	return `locales/${provided.language}.json`;
+}
+/**
+* Returns true for a release that the page can load. Such a release has a catalogue in the page's
+* language, and the provided versions meet its requirements.
+*/
+function loadedBy(listed, provided) {
+	const { files, requires } = listed.release;
+	return Object.hasOwn(files, catalogueOf(provided)) && unmetRequirements(requires, provided.versions).length === 0;
+}
+/**
+* Returns the words that the bytes of a catalogue contain, or undefined for bytes that are not a
+* JSON object.
+*/
+function wordsIn(bytes) {
+	let value;
+	try {
+		value = JSON.parse(new TextDecoder().decode(bytes));
+	} catch {
+		return;
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	return value;
+}
+/**
+* Returns a release with its words in the page's language. The step fetches the words and checks
+* them against the integrity in the release's description.
+*
+* @remarks
+*   The function returns the release unchanged when the page cannot load it. It also returns the
+*   release unchanged when the catalogue fails to load, has another digest or is not a JSON object.
+*   The page then fetches those words itself.
+*/
+async function withWords(fetching, listed, provided) {
+	const path = catalogueOf(provided);
+	const integrity = listed.release.files[path];
+	if (integrity === void 0 || !loadedBy(listed, provided)) return listed;
+	const bytes = await bytesOf(fetching, new URL(path, listed.base).href);
+	if (typeof bytes === "string" || await integrityOf(bytes) !== integrity) return listed;
+	const words = wordsIn(bytes);
+	return words === void 0 ? listed : {
+		...listed,
+		words
+	};
+}
+/**
+* Returns the content security policy of a document that lists releases.
+*
+* @remarks
+*   The policy contains `script-src` alone. A `connect-src` would restrict every other request the
+*   product makes, and the page fetches a release's catalogues with their integrity.
+*/
+async function policyOf(listed, provided, importMap) {
+	const urls = [...listed.map(({ base }) => base), ...Object.values(provided.imports)];
+	const origins = new Set(urls.flatMap((url) => URL.canParse(url) ? [new URL(url).origin] : []));
+	const digest = await integrityOf(new TextEncoder().encode(importMap));
+	return `script-src ${[
+		"'self'",
+		...[...origins].toSorted(),
+		`'${digest}'`
+	].join(" ")}`;
+}
+/**
+* Returns the parts of the document that depend on the deployment, after the step fetches each
+* release's description and checks it against the deployment.
+*
+* @remarks
+*   The step leaves a release out of the document and lists it in `refused` where its
+*   `plugin.json` fails to load, has a digest other than the pinned one, does not parse or is not a
+*   release description. The step writes the words of each release that the page can load into the
+*   deployment. It also writes the module preloads of the release's manifest and of the modules
+*   that the manifest imports.
+* @param deployment - The releases the product loads at run time.
+* @param provided - The product build's `.product/provided.json`.
+* @param options - How the step fetches a release's files.
+*/
+async function deployDocument(deployment, provided, options = {}) {
+	const fetching = options.fetching ?? FETCHING;
+	const outcomes = await Promise.all(deployment.releases.map((one) => listedOf(fetching, one)));
+	const found = outcomes.flatMap((outcome) => "release" in outcome ? [outcome] : []);
+	const listed = await Promise.all(found.map((one) => withWords(fetching, one, provided)));
+	const read = {
+		id: deployment.id,
+		modules: modulesOf(listed, provided),
+		provided: provided.versions,
+		releases: listed
+	};
+	const importMap = scriptText({
+		imports: provided.imports,
+		integrity: integrityMapOf(listed)
+	});
+	const preloads = listed.filter((one) => loadedBy(one, provided)).flatMap((one) => preloadsOf(read, one, MANIFEST_FILE));
+	return {
+		csp: await policyOf(listed, provided, importMap),
+		deployment: scriptText(read),
+		importMap,
+		preloads: [...new Map(preloads.map((preload) => [preload.href, preload])).values()],
+		refused: outcomes.flatMap((outcome) => "release" in outcome ? [] : [outcome]),
+		releases: listed.map(({ release }) => release.id)
+	};
+}
+/**
+* Returns a product's built document with the parts that depend on the deployment. The policy, the
+* deployment's import map, the preloads and the deployment that the page reads take the place of
+* the build's import map.
+*
+* @remarks
+*   The function finds the import map with two string searches, so its time grows linearly with
+*   the length of the document.
+* @param html - The document the product's build wrote, which contains the build's import map.
+* @param deployed - The parts `deployDocument` returned.
+* @throws {@link Error} Where the document does not contain an import map. The build of a product
+*   without `runtime` writes such a document.
+*/
+function documentWith(html, deployed) {
+	const start = html.indexOf(IMPORT_MAP_START);
+	const end = start === -1 ? -1 : html.indexOf(SCRIPT_END, start + 25);
+	if (end === -1) throw new Error("The document does not contain an import map. Build the product with runtime to write one.");
+	const tags = [
+		`<meta http-equiv="Content-Security-Policy" content="${deployed.csp}" />`,
+		`<script type="importmap">${deployed.importMap}<\/script>`,
+		...deployed.preloads.map((preload) => moduleTagOf(preload)),
+		`<script type="application/json" id="${DEPLOYMENT_ELEMENT}">${deployed.deployment}<\/script>`
+	];
+	return `${html.slice(0, start)}${tags.join("\n    ")}${html.slice(end + 9)}`;
+}
+//#endregion
+export { DEPLOYMENT_ELEMENT, deployDocument, documentWith };

package/dist/document-CeEtZo2E.js

@@ -0,0 +1,38 @@
+import { deploymentProblems, lineOf } from "@stealthscale/sdk-core";
+//#region src/releases/document.ts
+/**
+* Reads the deployment a page's document states: the releases the page loads at run time, which
+* the deployment step writes into the document as JSON.
+*/
+/**
+* Id of the element that contains the deployment as JSON in a page's document.
+*/
+const DEPLOYMENT_ELEMENT = "stealth-deployment";
+/**
+* Returns the deployment a document states, the faults of one the page cannot read, or none.
+*
+* @param document - The page's document, of which the function reads one element.
+*/
+function deploymentOf(document) {
+	const text = document.querySelector(`#${DEPLOYMENT_ELEMENT}`)?.textContent;
+	let value;
+	if (typeof text !== "string") return { kind: "none" };
+	try {
+		value = JSON.parse(text);
+	} catch (error) {
+		return {
+			faults: [`deployment: ${error.message}`],
+			kind: "malformed"
+		};
+	}
+	const problems = deploymentProblems(value);
+	return problems.length === 0 ? {
+		deployment: value,
+		kind: "deployment"
+	} : {
+		faults: problems.map((problem) => lineOf(problem)),
+		kind: "malformed"
+	};
+}
+//#endregion
+export { deploymentOf as n, DEPLOYMENT_ELEMENT as t };