@git.zone/tspack 1.1.0

package/ts/classes.tspack.ts

@@ -0,0 +1,170 @@
+import * as plugins from './plugins.js';
+import type { ITsPackConfig, ITsPackOptions, ITsPackResult, ITsPackVerifyOptions, ITsPackFileRecord, ITsPackManifest } from './interfaces.js';
+import { packArchive, verifyArchive } from './archive.js';
+import { digestFile, isCommit, isDigest, isPath, isVersion, jsonBytes, limits, noSymlinks, normalizeConfig, object,
+  readJson, requireValue, sha256, validateManifest } from './validation.js';
+export { TsPackError } from './validation.js';
+
+const exec = plugins.util.promisify(plugins.childProcess.execFile);
+const bundleMetadata = (manifest: Omit<ITsPackManifest, 'artifacts'>, id: string, files: Record<string, ITsPackFileRecord>) => ({
+  format: 'tspack.bundle.v1', packageName: manifest.packageName, version: manifest.version,
+  id, sourceCommit: manifest.sourceCommit, sourceDirty: manifest.sourceDirty,
+  publishable: manifest.publishable, configurationSha256: manifest.configurationSha256, files,
+});
+
+/** Packages explicit code/assets. Compilation, publishing and runtime installation have separate owners. */
+export class TsPack {
+  constructor(private readonly cwd = process.cwd()) {}
+
+  private async source(root: string, version: string, release: boolean) {
+    const run = async (...args: string[]) => (await exec('git', args, { cwd: root, maxBuffer: 4 * 1024 ** 2 })).stdout.trim();
+    const commit = await run('rev-parse', 'HEAD');
+    requireValue(isCommit(commit), 'source_state', 'A committed Git source identity is required.');
+    const dirty = (await run('status', '--porcelain')).length !== 0;
+    if (release) {
+      requireValue(!dirty && await run('rev-parse', `refs/tags/v${version}^{commit}`) === commit,
+        'source_state', 'Release packaging requires clean source at its matching version tag.');
+    }
+    return { commit, dirty };
+  }
+
+  public async pack(configArg?: ITsPackConfig, optionsArg: ITsPackOptions = {}): Promise<ITsPackResult> {
+    object(optionsArg, ['release', 'reuse']);
+    requireValue((optionsArg.release === undefined || typeof optionsArg.release === 'boolean') &&
+      (optionsArg.reuse === undefined || typeof optionsArg.reuse === 'boolean') &&
+      (!optionsArg.reuse || optionsArg.release), 'invalid_config', 'Reuse requires release mode.');
+    const root = await plugins.fs.realpath(this.cwd);
+    const { value: packageJson } = await readJson(plugins.path.join(root, 'package.json'));
+    object(packageJson);
+    requireValue(typeof packageJson.name === 'string' && packageJson.name.length <= 214 && isVersion(packageJson.version),
+      'invalid_config', 'Package metadata requires a name and version.');
+    const config = normalizeConfig(configArg ?? new plugins.smartconfig.Smartconfig(root).dataFor('@git.zone/tspack', {}), packageJson.name);
+    requireValue(config.bundles.every((bundle) => isPath(`${config.name}-${packageJson.version}-${bundle.id}.tar.gz`)),
+      'invalid_config', 'Archive names exceed the portable path limit.');
+    const configurationSha256 = sha256(jsonBytes(config));
+    const source = await this.source(root, packageJson.version, optionsArg.release === true);
+    const outputRoot = await noSymlinks(root, config.outputDirectory, true);
+    const releaseName = `${config.name}-${packageJson.version}-${source.commit.slice(0, 12)}`;
+    if (optionsArg.reuse) {
+      const directory = plugins.path.join(outputRoot, releaseName);
+      let exists = true;
+      try { await plugins.fs.lstat(directory); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') exists = false; else throw error; }
+      if (exists) {
+        const result = await this.verify(directory, { requireRelease: true, expectedSourceCommit: source.commit });
+        requireValue(result.manifest.configurationSha256 === configurationSha256 && result.manifest.packageName === packageJson.name &&
+          result.manifest.version === packageJson.version, 'integrity', 'Retained release set belongs to another configuration.');
+        return { ...result, reused: true };
+      }
+    }
+    await plugins.fs.mkdir(outputRoot, { recursive: true });
+    const stage = await plugins.fs.mkdtemp(plugins.path.join(outputRoot, '.tspack-'));
+    const assets = plugins.path.join(stage, 'assets');
+    await plugins.fs.mkdir(assets);
+    await plugins.fs.mkdir(plugins.path.join(stage, 'bundles'));
+    try {
+      const manifest: ITsPackManifest = {
+        format: 'tspack.release.v1', packageName: packageJson.name, name: config.name, version: packageJson.version,
+        sourceCommit: source.commit, sourceDirty: source.dirty, publishable: optionsArg.release === true,
+        configurationSha256, artifacts: [],
+      };
+      let total = 0;
+      for (const bundle of config.bundles) {
+        const directory = plugins.path.join(stage, 'bundles', bundle.id);
+        await plugins.fs.mkdir(directory);
+        const files: Record<string, ITsPackFileRecord> = Object.create(null);
+        for (const file of bundle.files) {
+          const input = await noSymlinks(root, file.source);
+          const handle = await plugins.fs.open(input, plugins.nodeFs.constants.O_RDONLY | plugins.nodeFs.constants.O_NOFOLLOW);
+          try {
+            const before = await handle.stat({ bigint: true });
+            requireValue(before.isFile() && before.size <= BigInt(limits.file), 'unsafe_input', 'Expected a bounded regular input file.');
+            total += Number(before.size);
+            requireValue(total <= limits.total, 'unsafe_input', 'Package inputs exceed the total byte limit.');
+            const destination = plugins.path.join(directory, file.path);
+            await plugins.fs.mkdir(plugins.path.dirname(destination), { recursive: true });
+            const hash = plugins.crypto.createHash('sha256');
+            let size = 0;
+            const meter = new plugins.stream.Transform({ transform(chunk: Buffer, _encoding, callback) {
+              size += chunk.length;
+              if (size > Number(before.size)) { callback(new Error('Input changed while copying.')); return; }
+              hash.update(chunk); callback(null, chunk);
+            } });
+            await plugins.streamPromises.pipeline(handle.createReadStream({ autoClose: false }), meter,
+              plugins.nodeFs.createWriteStream(destination, { flags: 'wx', mode: 0o600 }));
+            const after = await handle.stat({ bigint: true });
+            const current = await plugins.fs.lstat(input, { bigint: true });
+            requireValue(size === Number(before.size) && ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs'].every((key) =>
+              before[key as keyof typeof before] === after[key as keyof typeof after] &&
+              before[key as keyof typeof before] === current[key as keyof typeof current]),
+            'integrity', 'Input changed while copying.');
+            const record = { sha256: hash.digest('hex'), size, mode: (file.executable ? 0o755 : 0o644) as 493 | 420 };
+            requireValue(!file.sha256 || file.sha256 === record.sha256, 'integrity', 'Input does not match its pinned digest.');
+            files[file.path] = record;
+          } finally { await handle.close(); }
+        }
+        const metadata = jsonBytes(bundleMetadata(manifest, bundle.id, files));
+        requireValue(metadata.length <= limits.json, 'invalid_config', 'Bundle metadata exceeds its limit.');
+        await plugins.fs.writeFile(plugins.path.join(directory, 'tspack.json'), metadata, { flag: 'wx' });
+        files['tspack.json'] = { sha256: sha256(metadata), size: metadata.length, mode: 0o644 };
+        const name = `${config.name}-${packageJson.version}-${bundle.id}.tar.gz`;
+        await packArchive(directory, plugins.path.join(assets, name), files);
+        manifest.artifacts.push({ id: bundle.id, name, ...await digestFile(plugins.path.join(assets, name)), files });
+      }
+      const finalSource = await this.source(root, packageJson.version, optionsArg.release === true);
+      requireValue(finalSource.commit === source.commit && finalSource.dirty === source.dirty, 'source_state', 'Source identity changed while packaging.');
+      validateManifest(manifest);
+      const metadata = jsonBytes(manifest);
+      const manifestSha256 = sha256(metadata);
+      await plugins.fs.writeFile(plugins.path.join(assets, 'tspack-manifest.json'), metadata, { flag: 'wx' });
+      await plugins.fs.writeFile(plugins.path.join(assets, 'SHA256SUMS.txt'), this.checksums(manifest, manifestSha256), { flag: 'wx' });
+      await this.verify(assets, { expectedManifestSha256: manifestSha256 });
+      const name = optionsArg.release ? releaseName : `${releaseName}-qualification-${manifestSha256.slice(0, 16)}`;
+      const output = plugins.path.join(outputRoot, name);
+      let exists = true;
+      try { await plugins.fs.lstat(output); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') exists = false; else throw error; }
+      requireValue(!exists, 'exists', 'A sealed set already occupies this output; use verified release reuse or a separate output directory.');
+      await plugins.fs.rename(assets, output);
+      return { directory: output, manifest, manifestSha256, reused: false };
+    } finally { await plugins.fs.rm(stage, { recursive: true, force: true }); }
+  }
+
+  private checksums(manifest: ITsPackManifest, manifestSha256: string): string {
+    return [...manifest.artifacts.map((artifact) => [artifact.name, artifact.sha256]), ['tspack-manifest.json', manifestSha256]]
+      .sort(([a], [b]) => a!.localeCompare(b!, 'en')).map(([name, hash]) => `${hash}  ${name}`).join('\n') + '\n';
+  }
+
+  public async verify(directoryArg: string, optionsArg: ITsPackVerifyOptions = {}): Promise<ITsPackResult> {
+    object(optionsArg, ['expectedManifestSha256', 'expectedSourceCommit', 'requireRelease']);
+    requireValue((optionsArg.expectedManifestSha256 === undefined || isDigest(optionsArg.expectedManifestSha256)) &&
+      (optionsArg.expectedSourceCommit === undefined || isCommit(optionsArg.expectedSourceCommit)) &&
+      (optionsArg.requireRelease === undefined || typeof optionsArg.requireRelease === 'boolean'),
+    'invalid_config', 'Invalid verification identity.');
+    const directory = plugins.path.resolve(this.cwd, directoryArg);
+    requireValue((await plugins.fs.lstat(directory)).isDirectory() && await plugins.fs.realpath(directory) === directory,
+      'unsafe_input', 'A canonical regular artifact directory is required.');
+    const { value, bytes } = await readJson(plugins.path.join(directory, 'tspack-manifest.json'));
+    const manifestSha256 = sha256(bytes);
+    validateManifest(value);
+    const manifest = value;
+    requireValue((!optionsArg.expectedManifestSha256 || optionsArg.expectedManifestSha256 === manifestSha256) &&
+      (!optionsArg.expectedSourceCommit || optionsArg.expectedSourceCommit === manifest.sourceCommit) &&
+      (!optionsArg.requireRelease || manifest.publishable), 'integrity', 'Artifact set does not match its required identity.');
+    const names = (await plugins.fs.readdir(directory)).sort();
+    requireValue(names.join('\n') === [...manifest.artifacts.map((artifact) => artifact.name), 'tspack-manifest.json', 'SHA256SUMS.txt'].sort().join('\n'),
+      'integrity', 'Artifact directory has an unexpected file set.');
+    const checksumPath = plugins.path.join(directory, 'SHA256SUMS.txt');
+    const checksumStat = await plugins.fs.lstat(checksumPath);
+    requireValue(checksumStat.isFile() && checksumStat.size <= 32 * 1024 &&
+      await plugins.fs.readFile(checksumPath, 'utf8') === this.checksums(manifest, manifestSha256), 'integrity', 'Artifact-set checksums disagree.');
+    for (const artifact of manifest.artifacts) {
+      const file = plugins.path.join(directory, artifact.name);
+      const actual = await digestFile(file);
+      requireValue(actual.size === artifact.size && actual.sha256 === artifact.sha256, 'integrity', 'Archive integrity mismatch.');
+      const { ['tspack.json']: _metadata, ...files } = artifact.files;
+      await verifyArchive(file, artifact, bundleMetadata(manifest, artifact.id, files));
+    }
+    return { directory, manifest, manifestSha256, reused: false };
+  }
+}

package/ts/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.js';
+export * from './classes.tspack.js';
+export { runCli } from './tspack.cli.js';

package/ts/interfaces.ts

@@ -0,0 +1,68 @@
+export interface ITsPackFile {
+  /** Project-relative regular input file. Ancestor symlinks are rejected. */
+  source: string;
+  /** Portable relative name inside the bundle. */
+  path: string;
+  executable?: boolean;
+  /** Optional upstream identity, verified before assembly. */
+  sha256?: string;
+}
+
+export interface ITsPackBundle {
+  id: string;
+  files: ITsPackFile[];
+}
+
+export interface ITsPackConfig {
+  schemaVersion: 1;
+  /** Defaults to the package name with its scope separator replaced by a hyphen. */
+  name?: string;
+  outputDirectory?: string;
+  bundles: ITsPackBundle[];
+}
+
+export interface ITsPackOptions {
+  /** Requires clean source at the package's vVERSION tag. */
+  release?: boolean;
+  /** Reuse a verified existing sealed set for this exact tagged source/configuration. */
+  reuse?: boolean;
+}
+
+export interface ITsPackFileRecord {
+  sha256: string;
+  size: number;
+  mode: 420 | 493;
+}
+
+export interface ITsPackArtifact {
+  id: string;
+  name: string;
+  sha256: string;
+  size: number;
+  files: Record<string, ITsPackFileRecord>;
+}
+
+export interface ITsPackManifest {
+  format: 'tspack.release.v1';
+  packageName: string;
+  name: string;
+  version: string;
+  sourceCommit: string;
+  sourceDirty: boolean;
+  publishable: boolean;
+  configurationSha256: string;
+  artifacts: ITsPackArtifact[];
+}
+
+export interface ITsPackResult {
+  directory: string;
+  manifest: ITsPackManifest;
+  manifestSha256: string;
+  reused: boolean;
+}
+
+export interface ITsPackVerifyOptions {
+  expectedManifestSha256?: string;
+  expectedSourceCommit?: string;
+  requireRelease?: boolean;
+}

package/ts/plugins.ts

@@ -0,0 +1,16 @@
+// Node native modules
+import * as fs from 'node:fs/promises';
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import * as stream from 'node:stream';
+import * as streamPromises from 'node:stream/promises';
+import * as zlib from 'node:zlib';
+import * as childProcess from 'node:child_process';
+import * as util from 'node:util';
+export { fs, nodeFs, path, crypto, stream, streamPromises, zlib, childProcess, util };
+
+// @push.rocks modules
+import * as smartarchive from '@push.rocks/smartarchive';
+import * as smartconfig from '@push.rocks/smartconfig';
+export { smartarchive, smartconfig };

package/ts/tspack.cli.ts

@@ -0,0 +1,44 @@
+import { TsPack, TsPackError } from './classes.tspack.js';
+import * as plugins from './plugins.js';
+import type { ITsPackConfig } from './interfaces.js';
+import { readJson } from './validation.js';
+
+export async function runCli(args = process.argv.slice(2)): Promise<void> {
+  try {
+    if (args.length === 0 || args[0] === '--help' || args[0] === 'help') {
+      console.log('tspack pack [--release] [--reuse] [--config <json-file>]\ntspack verify <artifact-directory> [--release] [--sha256 <manifest-digest>]');
+      return;
+    }
+    const command = args[0];
+    const values = args.slice(1);
+    const directory = command === 'verify' ? values.shift() : undefined;
+    let release = false;
+    let reuse = false;
+    let configFile: string | undefined;
+    let expectedManifestSha256: string | undefined;
+    const used = new Set();
+    while (values.length) {
+      const option = values.shift()!;
+      if (used.has(option)) throw new TsPackError('arguments', 'Duplicate command option.');
+      used.add(option);
+      if (option === '--release') release = true;
+      else if (option === '--reuse' && command === 'pack') reuse = true;
+      else if ((option === '--config' && command === 'pack') || (option === '--sha256' && command === 'verify')) {
+        const value = values.shift();
+        if (!value || value.startsWith('--')) throw new TsPackError('arguments', 'Command option requires a value.');
+        if (option === '--config') configFile = value; else expectedManifestSha256 = value;
+      } else throw new TsPackError('arguments', 'Unknown command option.');
+    }
+    const pack = new TsPack();
+    const result = command === 'pack'
+      ? await pack.pack(configFile ? (await readJson(plugins.path.resolve(configFile))).value as ITsPackConfig : undefined, { release, reuse })
+      : command === 'verify' && directory && !directory.startsWith('--')
+      ? await pack.verify(directory, { requireRelease: release, expectedManifestSha256 })
+      : (() => { throw new TsPackError('arguments', 'Expected pack or verify with its required arguments.'); })();
+    console.log(JSON.stringify({ directory: result.directory, manifestSha256: result.manifestSha256,
+      publishable: result.manifest.publishable, reused: result.reused, bundles: result.manifest.artifacts.length }));
+  } catch (error) {
+    console.error(error instanceof TsPackError ? `tspack: ${error.code}: ${error.message}` : 'tspack: operation failed.');
+    process.exitCode = 1;
+  }
+}

package/ts/validation.ts

@@ -0,0 +1,136 @@
+import * as plugins from './plugins.js';
+import type { ITsPackConfig, ITsPackFileRecord, ITsPackManifest } from './interfaces.js';
+
+export const limits = { file: 2 * 1024 ** 3, total: 8 * 1024 ** 3, files: 10_000, json: 16 * 1024 ** 2 };
+export class TsPackError extends Error {
+  constructor(public readonly code: string, message: string) {
+    super(message);
+    this.name = 'TsPackError';
+  }
+}
+export function requireValue(value: unknown, code: string, message: string): asserts value {
+  if (!value) throw new TsPackError(code, message);
+}
+export const sha256 = (value: string | Buffer) => plugins.crypto.createHash('sha256').update(value).digest('hex');
+export const isDigest = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+export const isCommit = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(value);
+export const isName = (value: unknown): value is string => typeof value === 'string' && /^[a-z0-9][a-z0-9._-]{0,99}$/.test(value);
+export const isVersion = (value: unknown): value is string => typeof value === 'string' && value.length <= 64 && /^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(value);
+export const isPath = (value: unknown): value is string => typeof value === 'string' && value.length <= 240 &&
+  /^[a-zA-Z0-9@_+./-]+$/.test(value) && !value.startsWith('/') && value.split('/').every((part) => part && part !== '.' && part !== '..');
+export const jsonBytes = (value: unknown) => Buffer.from(JSON.stringify(value, null, 2) + '\n');
+
+export function object(value: unknown, allowed?: readonly string[]): asserts value is Record<string, unknown> {
+  requireValue(value && typeof value === 'object' && !Array.isArray(value) && !plugins.util.types.isProxy(value) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value)), 'invalid_config', 'Expected a plain record.');
+  requireValue(Reflect.ownKeys(value).every((key) => typeof key === 'string' &&
+    (!allowed || allowed.includes(key)) && Object.getOwnPropertyDescriptor(value, key)?.enumerable &&
+    'value' in Object.getOwnPropertyDescriptor(value, key)!), 'invalid_config', 'Unexpected record property.');
+}
+
+export function normalizeConfig(value: unknown, packageName: string): Required<ITsPackConfig> {
+  object(value, ['schemaVersion', 'name', 'outputDirectory', 'bundles']);
+  const name = value.name ?? packageName.replace(/^@/, '').replace('/', '-');
+  const outputDirectory = value.outputDirectory ?? 'dist_pack';
+  requireValue(value.schemaVersion === 1 && isName(name) && isPath(outputDirectory) &&
+    Array.isArray(value.bundles) && value.bundles.length > 0 && value.bundles.length <= 128,
+  'invalid_config', 'Invalid tspack configuration.');
+  let count = 0;
+  const bundles = value.bundles.map((bundle: unknown) => {
+    object(bundle, ['id', 'files']);
+    requireValue(isName(bundle.id) && Array.isArray(bundle.files) && bundle.files.length > 0,
+      'invalid_config', 'A bundle requires an identifier and explicit files.');
+    const files = bundle.files.map((file: unknown) => {
+      object(file, ['source', 'path', 'executable', 'sha256']);
+      requireValue(isPath(file.source) && isPath(file.path) && file.path !== 'tspack.json' && !file.path.startsWith('tspack.json/') &&
+        (!Object.hasOwn(file, 'executable') || typeof file.executable === 'boolean') &&
+        (!Object.hasOwn(file, 'sha256') || isDigest(file.sha256)), 'invalid_config', 'Invalid bundle file.');
+      return { source: file.source, path: file.path, executable: file.executable === true,
+        ...(file.sha256 ? { sha256: file.sha256 as string } : {}) };
+    }).sort((a, b) => a.path.localeCompare(b.path, 'en'));
+    count += files.length;
+    requireValue(new Set(files.map((file) => file.path)).size === files.length &&
+      files.every((file) => !files.some((other) => other.path.startsWith(file.path + '/'))),
+    'invalid_config', 'Bundle paths collide.');
+    return { id: bundle.id, files };
+  }).sort((a, b) => a.id.localeCompare(b.id, 'en'));
+  requireValue(count <= limits.files && new Set(bundles.map((bundle) => bundle.id)).size === bundles.length,
+    'invalid_config', 'Too many files or duplicate bundle identifiers.');
+  return { schemaVersion: 1, name, outputDirectory, bundles };
+}
+
+export function validateFileRecord(value: unknown): asserts value is ITsPackFileRecord {
+  object(value, ['sha256', 'size', 'mode']);
+  requireValue(isDigest(value.sha256) && typeof value.size === 'number' && Number.isSafeInteger(value.size) &&
+    value.size >= 0 && value.size <= limits.file && (value.mode === 0o644 || value.mode === 0o755),
+  'invalid_manifest', 'Invalid file identity.');
+}
+
+export function validateManifest(value: unknown): asserts value is ITsPackManifest {
+  object(value, ['format', 'packageName', 'name', 'version', 'sourceCommit', 'sourceDirty', 'publishable', 'configurationSha256', 'artifacts']);
+  requireValue(value.format === 'tspack.release.v1' && typeof value.packageName === 'string' && value.packageName.length <= 214 &&
+    isName(value.name) && isVersion(value.version) && isCommit(value.sourceCommit) &&
+    typeof value.sourceDirty === 'boolean' && typeof value.publishable === 'boolean' &&
+    (!value.publishable || !value.sourceDirty) && isDigest(value.configurationSha256) &&
+    Array.isArray(value.artifacts) && value.artifacts.length > 0 && value.artifacts.length <= 128,
+  'invalid_manifest', 'Invalid artifact-set manifest.');
+  const ids = new Set();
+  const names = new Set();
+  let total = 0;
+  let count = 0;
+  for (const artifact of value.artifacts) {
+    object(artifact, ['id', 'name', 'sha256', 'size', 'files']);
+    requireValue(isName(artifact.id) && !ids.has(artifact.id) &&
+      isPath(artifact.name) && artifact.name === `${value.name}-${value.version}-${artifact.id}.tar.gz` && !names.has(artifact.name) &&
+      isDigest(artifact.sha256) && typeof artifact.size === 'number' && Number.isSafeInteger(artifact.size) &&
+      artifact.size > 0 && artifact.size <= limits.total, 'invalid_manifest', 'Invalid archive identity.');
+    ids.add(artifact.id); names.add(artifact.name);
+    object(artifact.files);
+    requireValue(Object.hasOwn(artifact.files, 'tspack.json') && Object.keys(artifact.files).length > 1,
+      'invalid_manifest', 'Bundle metadata or selected files are missing.');
+    for (const [name, record] of Object.entries(artifact.files)) {
+      requireValue(isPath(name), 'invalid_manifest', 'Invalid archive member path.');
+      validateFileRecord(record);
+      total += record.size; count++;
+    }
+  }
+  requireValue(total <= limits.total && count <= limits.files + 128, 'invalid_manifest', 'Artifact set exceeds its limits.');
+}
+
+export async function noSymlinks(root: string, relative: string, allowMissing = false): Promise<string> {
+  requireValue(isPath(relative), 'unsafe_input', 'A canonical project-relative path is required.');
+  let current = root;
+  for (const part of relative.split('/')) {
+    current = plugins.path.join(current, part);
+    try {
+      requireValue(!(await plugins.fs.lstat(current)).isSymbolicLink(), 'unsafe_input', 'Symlink paths are not package inputs or outputs.');
+    } catch (error) {
+      if (allowMissing && (error as NodeJS.ErrnoException).code === 'ENOENT') break;
+      throw error;
+    }
+  }
+  return plugins.path.join(root, relative);
+}
+
+export async function readJson(file: string): Promise<{ value: unknown; bytes: Buffer }> {
+  const stat = await plugins.fs.lstat(file);
+  requireValue(stat.isFile() && stat.size <= limits.json, 'invalid_manifest', 'Expected bounded regular JSON metadata.');
+  const bytes = await plugins.fs.readFile(file);
+  requireValue(bytes.length <= limits.json, 'invalid_manifest', 'JSON metadata exceeds its limit.');
+  try { return { value: JSON.parse(bytes.toString('utf8')), bytes }; }
+  catch { throw new TsPackError('invalid_manifest', 'Invalid JSON metadata.'); }
+}
+
+export async function digestFile(file: string): Promise<{ sha256: string; size: number }> {
+  const stat = await plugins.fs.lstat(file);
+  requireValue(stat.isFile() && stat.size <= limits.total, 'integrity', 'Expected a bounded regular artifact file.');
+  const hash = plugins.crypto.createHash('sha256');
+  let size = 0;
+  for await (const chunk of plugins.nodeFs.createReadStream(file)) {
+    size += chunk.length;
+    requireValue(size <= stat.size, 'integrity', 'Artifact changed while reading.');
+    hash.update(chunk);
+  }
+  requireValue(size === stat.size, 'integrity', 'Artifact size changed while reading.');
+  return { sha256: hash.digest('hex'), size };
+}