@serve.zone/pallet-bundle 35.3.0

package/ts_bundle/verify.ts

@@ -0,0 +1,353 @@
+import * as plugins from './plugins.js';
+import { PalletBundleError, requireBundle } from './errors.js';
+import { canonicalPath, requireCanonicalDirectory } from './paths.js';
+import { palletBundleVersion } from './version.js';
+import {
+  isPalletControlTarget, palletControlBundleName, palletControlComponents, palletControlNoticeTrees, palletControlPackageName,
+  palletControlPaths, palletControlRecordKeys, palletControlRecordName, palletControlRoles, palletControlSourceInventories,
+  palletNativeTarget, type TPalletControlRole, type TPalletControlTarget,
+} from './inventory.js';
+
+/** The trusted identity of one Pallet release, as a consumer pins it. */
+export interface IPalletBundlePin {
+  readonly version: string;
+  readonly sourceCommit: string;
+  /** SHA-256 of the release's `tspack-manifest.json`, which pins every file of every bundle. */
+  readonly manifestSha256: string;
+}
+
+/** A bundle's files as its sealed tspack manifest records them. */
+export type TPalletSealedFiles = Readonly<Record<string, plugins.tspack.ITsPackFileRecord>>;
+
+export interface IPalletControlExecutable {
+  /** Absolute path inside the verified bundle directory. */
+  readonly path: string;
+  readonly sha256: string;
+}
+
+/** Who built a native executable, from its tsrust provenance. */
+export interface IPalletControlProvenance {
+  readonly projectName: string;
+  readonly projectVersion: string;
+  readonly gitCommit: string;
+}
+
+export interface IPalletControlBundle {
+  readonly directory: string;
+  readonly target: TPalletControlTarget;
+  readonly version: string;
+  readonly sourceCommit: string;
+  readonly sourceDirty: boolean;
+  /** The Deno the control executable was compiled with. */
+  readonly denoVersion: string;
+  readonly lockSha256: string;
+  readonly executables: Readonly<Record<TPalletControlRole, IPalletControlExecutable>>;
+  readonly provenance: Readonly<Record<Exclude<TPalletControlRole, 'control'>, IPalletControlProvenance>>;
+  readonly clockManifestSha256: string;
+  readonly dnsManifestSha256: string;
+  readonly vpnInventorySha256: string;
+  /** The digest `containerd-serve` compiles in; it pins containerd, its shim, runc and the pause image. */
+  readonly containerdManifestSha256: string;
+  readonly containerdVersion: string;
+  readonly runcVersion: string;
+  readonly files: TPalletSealedFiles;
+}
+
+/** A released bundle: every file verified against the pinned release manifest. */
+export interface IPalletVerifiedControlBundle extends IPalletControlBundle {
+  readonly manifestSha256: string;
+}
+
+/** What a build is expected to be; the consumer's pin, or the packaging step's own source identity. */
+export interface IPalletControlBuildExpectation {
+  readonly version: string;
+  readonly sourceCommit: string;
+  readonly sourceDirty: boolean;
+  readonly target: TPalletControlTarget;
+}
+
+const hash = /^[a-f0-9]{64}$/;
+const commit = /^[a-f0-9]{40}$/;
+const semver = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const executableMode = 0o755;
+const fileMode = 0o644;
+const maximumMetadataBytes = 2 * 1024 * 1024;
+
+type TRecord = Record<string, unknown>;
+const record = (valueArg: unknown): valueArg is TRecord =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg) &&
+  Object.getPrototypeOf(valueArg) === Object.prototype;
+const sameKeys = (valueArg: TRecord, keysArg: readonly string[]): boolean => {
+  const keys = Object.keys(valueArg);
+  return keys.length === keysArg.length && keysArg.every((key) => Object.hasOwn(valueArg, key));
+};
+const list = (valueArg: unknown): valueArg is readonly unknown[] => Array.isArray(valueArg);
+const safeName = (nameArg: unknown): nameArg is string =>
+  typeof nameArg === 'string' && nameArg.length <= 1024 && /^[A-Za-z0-9][A-Za-z0-9._+@/-]*$/.test(nameArg) &&
+  !nameArg.split('/').some((part) => ['', '.', '..'].includes(part));
+const invalid = (): never => { throw new PalletBundleError('invalid_release'); };
+
+export const validPalletBundlePin = (valueArg: unknown): valueArg is IPalletBundlePin =>
+  record(valueArg) && sameKeys(valueArg, ['version', 'sourceCommit', 'manifestSha256']) &&
+  typeof valueArg.version === 'string' && semver.test(valueArg.version) &&
+  typeof valueArg.sourceCommit === 'string' && commit.test(valueArg.sourceCommit) &&
+  typeof valueArg.manifestSha256 === 'string' && hash.test(valueArg.manifestSha256);
+
+/** Refuses a malformed pin, and a pin of another Pallet version than this package states. */
+export async function requirePalletBundlePin(pinArg: unknown): Promise<IPalletBundlePin> {
+  requireBundle(validPalletBundlePin(pinArg), 'invalid_options');
+  if (pinArg.version !== await palletBundleVersion()) throw new PalletBundleError('version_mismatch');
+  return Object.freeze({ version: pinArg.version, sourceCommit: pinArg.sourceCommit, manifestSha256: pinArg.manifestSha256 });
+}
+
+/** Reads one sealed file back and proves its bytes are the sealed record's. */
+async function readSealed(directoryArg: string, filesArg: TPalletSealedFiles, nameArg: string): Promise<Buffer> {
+  const sealed = filesArg[nameArg];
+  requireBundle(sealed && safeName(nameArg) && sealed.mode === fileMode && sealed.size <= maximumMetadataBytes, 'invalid_release');
+  const filename = plugins.path.join(directoryArg, nameArg);
+  const file = await plugins.fs.open(filename, plugins.fsConstants.O_RDONLY | plugins.fsConstants.O_NOFOLLOW)
+    .catch(() => { throw new PalletBundleError('invalid_release'); });
+  try {
+    const info = await file.stat();
+    requireBundle(info.isFile() && info.size === sealed.size, 'invalid_release');
+    const bytes = Buffer.alloc(info.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const { bytesRead } = await file.read(bytes, offset, bytes.length - offset, offset);
+      requireBundle(bytesRead > 0, 'invalid_release');
+      offset += bytesRead;
+    }
+    requireBundle(plugins.crypto.createHash('sha256').update(bytes).digest('hex') === sealed.sha256, 'artifact_mismatch');
+    return bytes;
+  } finally {
+    await file.close();
+  }
+}
+
+async function readJson(directoryArg: string, filesArg: TPalletSealedFiles, nameArg: string): Promise<unknown> {
+  const bytes = await readSealed(directoryArg, filesArg, nameArg);
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { return invalid(); }
+}
+
+/** The files below the prefixes, as the sealed manifest names them. */
+const below = (filesArg: TPalletSealedFiles, prefixesArg: readonly string[]): string[] =>
+  Object.keys(filesArg).filter((name) => prefixesArg.some((prefix) => name.startsWith(prefix))).sort();
+const sameSet = (leftArg: readonly string[], rightArg: readonly string[]): boolean =>
+  leftArg.length === rightArg.length && [...leftArg].sort().every((name, index) => name === [...rightArg].sort()[index]);
+
+/** The facts of a checked control record that a bundle states. */
+type TPalletControlRecordFacts = Pick<IPalletControlBundle, 'denoVersion' | 'lockSha256' | 'clockManifestSha256' |
+  'containerdManifestSha256' | 'dnsManifestSha256' | 'vpnInventorySha256'>;
+
+/** The control record: its identity, its fixed paths, and each declared file's sealed record. */
+function checkRecord(recordArg: unknown, filesArg: TPalletSealedFiles,
+  expectedArg: IPalletControlBuildExpectation): TPalletControlRecordFacts {
+  requireBundle(record(recordArg) && sameKeys(recordArg, palletControlRecordKeys), 'invalid_release');
+  const control = recordArg;
+  const compiler = control.compiler;
+  requireBundle(control.packageName === palletControlPackageName && control.version === expectedArg.version &&
+    control.sourceCommit === expectedArg.sourceCommit && control.sourceDirty === expectedArg.sourceDirty &&
+    control.target === expectedArg.target && control.expectedUid === palletControlPaths.expectedUid &&
+    control.dataRoot === palletControlPaths.dataRoot && control.socketPath === palletControlPaths.socketPath &&
+    control.runtimeSocketPath === palletControlPaths.runtimeSocketPath &&
+    typeof control.lockSha256 === 'string' && hash.test(control.lockSha256) &&
+    record(compiler) && Object.values(compiler).every((value) => typeof value === 'string') &&
+    typeof compiler.deno === 'string' && semver.test(compiler.deno), 'invalid_release');
+  const componentDigest = (componentArg: keyof typeof palletControlComponents): string => {
+    const component = palletControlComponents[componentArg];
+    const digest = control[component.recordKey];
+    requireBundle(typeof digest === 'string' && hash.test(digest) && filesArg[component.manifest]?.sha256 === digest &&
+      filesArg[component.manifest].mode === fileMode, 'invalid_release');
+    return digest;
+  };
+  const facts: TPalletControlRecordFacts = {
+    denoVersion: compiler.deno, lockSha256: control.lockSha256,
+    clockManifestSha256: componentDigest('clock'), containerdManifestSha256: componentDigest('containerd'),
+    dnsManifestSha256: componentDigest('dns'), vpnInventorySha256: componentDigest('vpn'),
+  };
+  const declared = control.files;
+  requireBundle(record(declared) && Object.keys(declared).length > 0, 'invalid_release');
+  for (const [name, described] of Object.entries(declared)) {
+    const sealed = filesArg[name];
+    requireBundle(safeName(name) && record(described) && sameKeys(described, ['sha256', 'size']) && sealed &&
+      described.sha256 === sealed.sha256 && described.size === sealed.size, 'invalid_release');
+  }
+  // Every executable the bundle carries is one the control record declares.
+  for (const [name, sealed] of Object.entries(filesArg)) {
+    requireBundle(safeName(name) && (sealed.mode === fileMode || (sealed.mode === executableMode && Object.hasOwn(declared, name))),
+      'invalid_release');
+  }
+  for (const role of Object.values(palletControlRoles)) {
+    requireBundle(Object.hasOwn(declared, role.path) && filesArg[role.path]?.mode === executableMode &&
+      filesArg[role.path].size > 0, 'invalid_release');
+    if (role.provenance) {
+      requireBundle(Object.hasOwn(declared, role.provenance.path) && filesArg[role.provenance.path]?.mode === fileMode,
+        'invalid_release');
+    }
+  }
+  return facts;
+}
+
+/** A listing component: its manifest names exactly the files below its directory. */
+async function checkListing(directoryArg: string, filesArg: TPalletSealedFiles, manifestArg: string,
+  prefixArg: string): Promise<TRecord> {
+  const manifest = await readJson(directoryArg, filesArg, manifestArg);
+  requireBundle(record(manifest) && list(manifest.files) && manifest.files.length > 0, 'invalid_release');
+  const listed: string[] = [];
+  for (const entry of manifest.files) {
+    requireBundle(record(entry) && safeName(entry.path) && typeof entry.sha256 === 'string' && hash.test(entry.sha256) &&
+      Number.isSafeInteger(entry.size) && (entry.mode === executableMode || entry.mode === fileMode), 'invalid_release');
+    const name = `${prefixArg}${entry.path}`;
+    const sealed = filesArg[name];
+    requireBundle(name !== manifestArg && sealed && sealed.sha256 === entry.sha256 && sealed.size === entry.size &&
+      sealed.mode === entry.mode, 'invalid_release');
+    listed.push(name);
+  }
+  requireBundle(new Set(listed).size === listed.length && sameSet(below(filesArg, [prefixArg]), [manifestArg, ...listed]),
+    'invalid_release');
+  return manifest;
+}
+
+/** A `tsrust.native-notices` tree: its manifest names every file below the prefix by digest. */
+async function checkNoticeTree(directoryArg: string, filesArg: TPalletSealedFiles, prefixArg: string): Promise<void> {
+  const manifestName = `${prefixArg}manifest.json`;
+  const manifest = await readJson(directoryArg, filesArg, manifestName);
+  requireBundle(record(manifest) && manifest.format === 'tsrust.native-notices' && record(manifest.files), 'invalid_release');
+  const named = Object.entries(manifest.files);
+  requireBundle(named.length > 0 && named.length <= 1024 && !Object.hasOwn(manifest.files, 'manifest.json'), 'invalid_release');
+  for (const [name, digest] of named) {
+    const sealed = filesArg[`${prefixArg}${name}`];
+    requireBundle(safeName(name) && typeof digest === 'string' && hash.test(digest) && sealed?.sha256 === digest &&
+      sealed.mode === fileMode, 'invalid_release');
+  }
+  requireBundle(sameSet(below(filesArg, [prefixArg]), [manifestName, ...named.map(([name]) => `${prefixArg}${name}`)]),
+    'invalid_release');
+}
+
+/** A notice and corresponding-source inventory: its manifest lists every file below its prefixes. */
+async function checkSourceInventory(directoryArg: string, filesArg: TPalletSealedFiles, manifestArg: string,
+  prefixesArg: readonly string[]): Promise<void> {
+  const manifest = await readJson(directoryArg, filesArg, manifestArg);
+  requireBundle(record(manifest) && list(manifest.files) && manifest.files.length > 0, 'invalid_release');
+  const listed: string[] = [];
+  for (const entry of manifest.files) {
+    requireBundle(record(entry), 'invalid_release');
+    const path = entry.path;
+    requireBundle(safeName(path) && path !== manifestArg && prefixesArg.some((prefix) => path.startsWith(prefix)) &&
+      typeof entry.sha256 === 'string' && hash.test(entry.sha256) && Number.isSafeInteger(entry.size) &&
+      filesArg[path]?.sha256 === entry.sha256 && filesArg[path].size === entry.size &&
+      filesArg[path].mode === fileMode, 'invalid_release');
+    listed.push(path);
+  }
+  requireBundle(new Set(listed).size === listed.length && sameSet(below(filesArg, prefixesArg), [manifestArg, ...listed]),
+    'invalid_release');
+}
+
+/** One native executable's tsrust provenance, bound to the sealed executable and this bundle's target. */
+async function checkProvenance(directoryArg: string, filesArg: TPalletSealedFiles, roleArg: Exclude<TPalletControlRole, 'control'>,
+  expectedArg: IPalletControlBuildExpectation): Promise<IPalletControlProvenance> {
+  const role = palletControlRoles[roleArg];
+  const description = role.provenance!;
+  const provenance = await readJson(directoryArg, filesArg, description.path);
+  requireBundle(record(provenance), 'invalid_release');
+  const build = provenance.buildInfo;
+  requireBundle(record(build), 'invalid_release');
+  const own = roleArg === 'runtime';
+  requireBundle(provenance.format === 'tsrust.build-provenance.v2' && provenance.binarySha256 === filesArg[role.path].sha256 &&
+    build.projectName === description.projectName && build.binary === description.binary &&
+    build.target === palletNativeTarget(expectedArg.target) &&
+    typeof build.projectVersion === 'string' && semver.test(build.projectVersion) &&
+    typeof build.gitCommit === 'string' && commit.test(build.gitCommit) &&
+    build.gitDirty === (own ? expectedArg.sourceDirty : false) &&
+    (!own || (build.projectVersion === expectedArg.version && build.gitCommit === expectedArg.sourceCommit)), 'invalid_release');
+  return Object.freeze({ projectName: description.projectName, projectVersion: build.projectVersion, gitCommit: build.gitCommit });
+}
+
+/**
+ * Checks a control build directory against the sealed records of its files: the control record,
+ * every executable's role and provenance, the component manifests and the notice and source
+ * inventories. Pallet's packaging runs this over every build before sealing it, with the build's
+ * own source identity; consumers use {@link verifyPalletControlBundle}, which also binds the pin.
+ */
+export async function inspectPalletControlBuild(directoryArg: string, filesArg: TPalletSealedFiles,
+  expectedArg: IPalletControlBuildExpectation): Promise<IPalletControlBundle> {
+  const directory = canonicalPath(directoryArg);
+  requireBundle(isPalletControlTarget(expectedArg.target) && semver.test(expectedArg.version) &&
+    commit.test(expectedArg.sourceCommit) && typeof expectedArg.sourceDirty === 'boolean' && record(filesArg), 'invalid_options');
+  await requireCanonicalDirectory(directory);
+  const control = checkRecord(await readJson(directory, filesArg, palletControlRecordName), filesArg, expectedArg);
+  await checkListing(directory, filesArg, palletControlComponents.clock.manifest, palletControlComponents.clock.directory);
+  const containerd = await checkListing(directory, filesArg, palletControlComponents.containerd.manifest,
+    palletControlComponents.containerd.directory);
+  requireBundle(typeof containerd.containerdVersion === 'string' && typeof containerd.runcVersion === 'string', 'invalid_release');
+  for (const tree of palletControlNoticeTrees) await checkNoticeTree(directory, filesArg, tree);
+  for (const inventory of palletControlSourceInventories) {
+    await checkSourceInventory(directory, filesArg, inventory.manifest, inventory.prefixes);
+  }
+  const provenance = {
+    store: await checkProvenance(directory, filesArg, 'store', expectedArg),
+    runtime: await checkProvenance(directory, filesArg, 'runtime', expectedArg),
+    guard: await checkProvenance(directory, filesArg, 'guard', expectedArg),
+    dns: await checkProvenance(directory, filesArg, 'dns', expectedArg),
+    vpn: await checkProvenance(directory, filesArg, 'vpn', expectedArg),
+  };
+  const executable = (roleArg: TPalletControlRole): IPalletControlExecutable => Object.freeze({
+    path: plugins.path.join(directory, palletControlRoles[roleArg].path), sha256: filesArg[palletControlRoles[roleArg].path].sha256,
+  });
+  return Object.freeze({
+    directory, target: expectedArg.target, version: expectedArg.version, sourceCommit: expectedArg.sourceCommit,
+    sourceDirty: expectedArg.sourceDirty, denoVersion: control.denoVersion, lockSha256: control.lockSha256,
+    executables: Object.freeze({ control: executable('control'), store: executable('store'), runtime: executable('runtime'),
+      guard: executable('guard'), dns: executable('dns'), vpn: executable('vpn') }),
+    provenance: Object.freeze(provenance),
+    clockManifestSha256: control.clockManifestSha256, dnsManifestSha256: control.dnsManifestSha256,
+    vpnInventorySha256: control.vpnInventorySha256, containerdManifestSha256: control.containerdManifestSha256,
+    containerdVersion: containerd.containerdVersion, runcVersion: containerd.runcVersion,
+    files: Object.freeze({ ...filesArg }),
+  });
+}
+
+/**
+ * Verifies an extracted release bundle of the pinned version: `filesArg` are the records of the
+ * sealed release manifest whose digest the pin states (tspack's `extractBundle` result), and the
+ * pin must name this package's own Pallet version.
+ */
+export async function verifyPalletControlBundle(directoryArg: string, filesArg: TPalletSealedFiles, pinArg: IPalletBundlePin,
+  targetArg: TPalletControlTarget): Promise<IPalletVerifiedControlBundle> {
+  const pin = await requirePalletBundlePin(pinArg);
+  requireBundle(isPalletControlTarget(targetArg), 'invalid_options');
+  const bundle = await inspectPalletControlBuild(directoryArg, filesArg,
+    { version: pin.version, sourceCommit: pin.sourceCommit, sourceDirty: false, target: targetArg });
+  return Object.freeze({ ...bundle, manifestSha256: pin.manifestSha256 });
+}
+
+/**
+ * Extracts and verifies the pinned bundle from a download directory that holds the release's
+ * `tspack-manifest.json`, `SHA256SUMS.txt` and the target's archive. The bundle is extracted into a
+ * fresh private directory below `stagingParentArg`, which the caller owns from then on.
+ */
+export async function extractPalletControlBundle(downloadDirectoryArg: string, targetArg: TPalletControlTarget,
+  stagingParentArg: string, pinArg: IPalletBundlePin, signalArg?: AbortSignal): Promise<IPalletVerifiedControlBundle> {
+  const pin = await requirePalletBundlePin(pinArg);
+  requireBundle(isPalletControlTarget(targetArg), 'invalid_options');
+  await requireCanonicalDirectory(canonicalPath(stagingParentArg));
+  let extracted: plugins.tspack.ITsPackExtractResult;
+  try {
+    extracted = await new plugins.tspack.TsPack().extractBundle(downloadDirectoryArg, targetArg, stagingParentArg, {
+      expectedManifestSha256: pin.manifestSha256, expectedSourceCommit: pin.sourceCommit, requireRelease: true,
+      ...(signalArg ? { signal: signalArg } : {}),
+    });
+  } catch (error) {
+    if (signalArg?.aborted) throw new PalletBundleError('aborted', { cause: error });
+    throw new PalletBundleError('invalid_release', { cause: error });
+  }
+  try {
+    requireBundle(extracted.manifest.packageName === palletControlPackageName &&
+      extracted.manifest.name === palletControlBundleName && extracted.manifest.version === pin.version, 'invalid_release');
+    return await verifyPalletControlBundle(extracted.directory, extracted.artifact.files, pin, targetArg);
+  } catch (error) {
+    await plugins.fs.rm(extracted.directory, { recursive: true, force: true });
+    throw error;
+  }
+}

package/ts_bundle/version.ts

@@ -0,0 +1,18 @@
+import * as plugins from './plugins.js';
+
+let ownVersion: Promise<string> | undefined;
+
+/**
+ * The Pallet version this package describes. The package is released from Pallet's repository with
+ * Pallet's own version, so this is the one bundle version whose inventory and contracts it states.
+ * It is read from the package manifest beside the compiled module, which is Pallet's root manifest
+ * in the repository and the published package's own manifest in `node_modules`.
+ */
+export const palletBundleVersion = (): Promise<string> => ownVersion ??= (async () => {
+  const manifest: unknown = JSON.parse(await plugins.fs.readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  const version = typeof manifest === 'object' && manifest !== null && 'version' in manifest ? manifest.version : undefined;
+  if (typeof version !== 'string' || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version)) {
+    throw new Error('The Pallet bundle package manifest carries no release version.');
+  }
+  return version;
+})();