@serve.zone/pallet-bundle 35.3.0

package/ts_bundle/classes.releaseclient.ts

@@ -0,0 +1,288 @@
+import * as plugins from './plugins.js';
+import { PalletBundleError, requireBundle } from './errors.js';
+import { canonicalPath } from './paths.js';
+import { isPalletControlTarget, palletControlBundleName, palletControlPackageName, palletControlRepository,
+  palletControlTargets, type TPalletControlTarget } from './inventory.js';
+import { requirePalletBundlePin, type IPalletBundlePin } from './verify.js';
+
+export interface IPalletReleaseClientOptions {
+  /** Private TLS qualification only; production uses the default trusted Gitea origin. */
+  origin?: string;
+  requestTimeoutMs?: number;
+  downloadTimeoutMs?: number;
+  /** Owning-code qualification only. */
+  fetch?: typeof fetch;
+}
+
+interface IReleaseAsset {
+  name: string;
+  size: number;
+  url: string;
+}
+
+/** Any JSON object, arrays included: the fields each check reads decide the rest. */
+const jsonObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null;
+const list = (valueArg: unknown): valueArg is readonly unknown[] => Array.isArray(valueArg);
+const identifier = (valueArg: unknown): valueArg is number => Number.isSafeInteger(valueArg) && Number(valueArg) > 0;
+const releaseAssetName = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,239}$/.test(valueArg);
+const archiveName = (versionArg: string, targetArg: TPalletControlTarget): string =>
+  `${palletControlBundleName}-${versionArg}-${targetArg}.tar.gz`;
+const metadataLimit = 16 * 1024 ** 2;
+const archiveLimit = 1024 ** 3;
+
+/**
+ * Anonymous HTTPS download of a pinned Pallet release from its Gitea repository. It owns the
+ * downloads and the release shape; tspack owns the format and content verification. A release is
+ * only ever selected by its pin: the version, the tagged source commit and the digest of its sealed
+ * manifest, which must match this package's own Pallet version.
+ */
+export class PalletReleaseClient {
+  private readonly origin: string;
+  private readonly requestTimeoutMs: number;
+  private readonly downloadTimeoutMs: number;
+  private readonly fetchOwner: typeof fetch;
+
+  constructor(optionsArg: IPalletReleaseClientOptions = {}) {
+    requireBundle(optionsArg && typeof optionsArg === 'object' && !plugins.nodeUtil.types.isProxy(optionsArg) &&
+      Object.getPrototypeOf(optionsArg) === Object.prototype &&
+      Object.keys(optionsArg).every((key) => ['origin', 'requestTimeoutMs', 'downloadTimeoutMs', 'fetch'].includes(key)),
+    'invalid_options');
+    this.origin = optionsArg.origin ?? 'https://code.foss.global';
+    this.requestTimeoutMs = optionsArg.requestTimeoutMs ?? 30_000;
+    this.downloadTimeoutMs = optionsArg.downloadTimeoutMs ?? 10 * 60_000;
+    this.fetchOwner = optionsArg.fetch ?? fetch;
+    requireBundle(typeof this.origin === 'string' && typeof this.fetchOwner === 'function' &&
+      [this.requestTimeoutMs, this.downloadTimeoutMs].every((value) =>
+        Number.isSafeInteger(value) && value >= 1 && value <= 15 * 60_000), 'invalid_options');
+    let origin: URL;
+    try { origin = new URL(this.origin); } catch { throw new PalletBundleError('invalid_options'); }
+    requireBundle(origin.protocol === 'https:' && origin.origin === this.origin, 'invalid_options');
+  }
+
+  /**
+   * Downloads the pinned release's manifest, checksums and the target's archive into a fresh
+   * private directory below `parentArg`, verifies the archive against the pinned manifest and hands
+   * the directory to the callback. The directory is removed when the callback settles, so the
+   * callback must finish with the files (for example `extractPalletControlBundle`) before it returns.
+   */
+  public async run<TResult>(pinArg: IPalletBundlePin, targetArg: TPalletControlTarget, parentArg: string,
+    callbackArg: (directoryArg: string, pinArg: IPalletBundlePin) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+    try {
+      return await this.download(pinArg, targetArg, parentArg, callbackArg, signalArg);
+    } catch (error) {
+      if (signalArg?.aborted) throw new PalletBundleError('aborted', { cause: error });
+      throw error;
+    }
+  }
+
+  private async download<TResult>(pinArg: IPalletBundlePin, targetArg: TPalletControlTarget, parentArg: string,
+    callbackArg: (directoryArg: string, pinArg: IPalletBundlePin) => Promise<TResult>, signalArg?: AbortSignal): Promise<TResult> {
+    const pin = await requirePalletBundlePin(pinArg);
+    requireBundle(isPalletControlTarget(targetArg) && typeof callbackArg === 'function' &&
+      (signalArg === undefined || signalArg instanceof AbortSignal), 'invalid_options');
+    const parent = canonicalPath(parentArg);
+    const assets = await this.resolveRelease(pin, signalArg);
+    const selected = ['tspack-manifest.json', 'SHA256SUMS.txt', archiveName(pin.version, targetArg)]
+      .map((name) => assets.find((asset) => asset.name === name)!);
+    const parentInfo = await plugins.fs.lstat(parent).catch(() => { throw new PalletBundleError('unsafe_path'); });
+    requireBundle(parentInfo.isDirectory() && await plugins.fs.realpath(parent) === parent, 'unsafe_path');
+    signalArg?.throwIfAborted();
+    const directory = await plugins.fs.mkdtemp(plugins.path.join(parent, '.pallet-download-'));
+    const owner = await plugins.fs.lstat(directory);
+    try {
+      // Sequential ownership bounds disk and network use; every response body settles before the next.
+      for (const asset of selected) {
+        await this.request(asset.url, signalArg, asset.name.endsWith('.tar.gz') ? this.downloadTimeoutMs : this.requestTimeoutMs,
+          async (response, signal) => {
+            const file = await plugins.fs.open(plugins.path.join(directory, asset.name),
+              plugins.fsConstants.O_WRONLY | plugins.fsConstants.O_CREAT | plugins.fsConstants.O_EXCL | plugins.fsConstants.O_NOFOLLOW,
+              0o600);
+            try {
+              await this.consume(response, asset.size, signal, async (chunk) => {
+                let offset = 0;
+                while (offset < chunk.length) {
+                  signal.throwIfAborted();
+                  const { bytesWritten } = await file.write(chunk, offset, chunk.length - offset);
+                  requireBundle(bytesWritten > 0, 'invalid_download');
+                  offset += bytesWritten;
+                }
+              }, asset.size);
+            } finally {
+              await file.close();
+            }
+          });
+      }
+      let verified: plugins.tspack.ITsPackBundleResult;
+      try {
+        verified = await new plugins.tspack.TsPack().verifyBundle(directory, targetArg, {
+          expectedManifestSha256: pin.manifestSha256, expectedSourceCommit: pin.sourceCommit, requireRelease: true,
+          ...(signalArg ? { signal: signalArg } : {}),
+        });
+      } catch (error) {
+        throw new PalletBundleError('invalid_release', { cause: error });
+      }
+      requireBundle(verified.manifest.packageName === palletControlPackageName &&
+        verified.manifest.name === palletControlBundleName && verified.manifest.version === pin.version, 'invalid_release');
+      signalArg?.throwIfAborted();
+      return await callbackArg(directory, pin);
+    } finally {
+      const current = await plugins.fs.lstat(directory);
+      requireBundle(current.isDirectory() && !current.isSymbolicLink() && current.dev === owner.dev && current.ino === owner.ino &&
+        current.uid === owner.uid && await plugins.fs.realpath(directory) === directory, 'unsafe_path');
+      await plugins.fs.rm(directory, { recursive: true });
+    }
+  }
+
+  /** The pinned release's assets, after its metadata proves it is the pinned sealed set. */
+  private async resolveRelease(pinArg: IPalletBundlePin, signalArg?: AbortSignal): Promise<IReleaseAsset[]> {
+    const tag = `v${pinArg.version}`;
+    const base = `${this.origin}/api/v1/repos/${palletControlRepository}`;
+    const release: unknown = await this.json(`${base}/releases/tags/${tag}`, signalArg, true);
+    requireBundle(jsonObject(release), 'invalid_release');
+    const releaseAssets = release.assets;
+    requireBundle(identifier(release.id) && release.draft === false && release.prerelease === false && release.tag_name === tag &&
+      release.target_commitish === pinArg.sourceCommit && list(releaseAssets) && releaseAssets.length <= 130,
+    'invalid_release');
+    const tagged: unknown = await this.json(`${base}/tags/${tag}`, signalArg);
+    requireBundle(jsonObject(tagged) && tagged.name === tag && jsonObject(tagged.commit) &&
+      tagged.commit.sha === pinArg.sourceCommit, 'invalid_release');
+    const names = new Set<string>();
+    const ids = new Set<number>();
+    const assets = releaseAssets.map((asset) => {
+      requireBundle(jsonObject(asset), 'invalid_release');
+      requireBundle(releaseAssetName(asset.name) && identifier(asset.id) && identifier(asset.size) &&
+        typeof asset.browser_download_url === 'string' && !names.has(asset.name) && !ids.has(asset.id), 'invalid_release');
+      this.url(asset.browser_download_url);
+      names.add(asset.name);
+      ids.add(asset.id);
+      return { name: asset.name, size: asset.size, url: asset.browser_download_url };
+    });
+    const canonical = new Set(['tspack-manifest.json', 'SHA256SUMS.txt',
+      ...palletControlTargets.map((target) => archiveName(pinArg.version, target))]);
+    const manifestAsset = assets.find((asset) => asset.name === 'tspack-manifest.json');
+    const checksumsAsset = assets.find((asset) => asset.name === 'SHA256SUMS.txt');
+    if (!manifestAsset || !checksumsAsset) {
+      if (assets.every((asset) => canonical.has(asset.name))) {
+        throw new PalletBundleError('release_pending', { missingAssets: [...canonical].filter((name) => !names.has(name)) });
+      }
+      throw new PalletBundleError('invalid_release');
+    }
+    requireBundle(manifestAsset.size <= metadataLimit && checksumsAsset.size <= metadataLimit, 'invalid_release');
+    const manifestBytes = await this.bytes(manifestAsset.url, manifestAsset.size, signalArg);
+    const checksumsBytes = await this.bytes(checksumsAsset.url, checksumsAsset.size, signalArg);
+    let metadata: plugins.tspack.ITsPackMetadataResult;
+    try {
+      metadata = new plugins.tspack.TsPack().verifyMetadata(manifestBytes, checksumsBytes, {
+        expectedManifestSha256: pinArg.manifestSha256, expectedSourceCommit: pinArg.sourceCommit, requireRelease: true,
+      });
+    } catch (error) {
+      throw new PalletBundleError('invalid_release', { cause: error });
+    }
+    const { manifest } = metadata;
+    requireBundle(manifest.packageName === palletControlPackageName && manifest.name === palletControlBundleName &&
+      manifest.version === pinArg.version && manifest.sourceCommit === pinArg.sourceCommit &&
+      manifest.artifacts.length === palletControlTargets.length &&
+      palletControlTargets.every((target) => manifest.artifacts.some((artifact) =>
+        artifact.id === target && artifact.kind === undefined && artifact.name === archiveName(pinArg.version, target) &&
+        artifact.size <= archiveLimit)), 'invalid_release');
+    const expected = new Map<string, number>([
+      ...manifest.artifacts.map((artifact) => [artifact.name, artifact.size] as const),
+      ['tspack-manifest.json', manifestBytes.length],
+      ['SHA256SUMS.txt', checksumsBytes.length],
+    ]);
+    const canonicalSubset = assets.every((asset) => expected.get(asset.name) === asset.size);
+    if (assets.length < expected.size && canonicalSubset) {
+      throw new PalletBundleError('release_pending', { missingAssets: [...expected.keys()].filter((name) => !names.has(name)) });
+    }
+    requireBundle(assets.length === expected.size && canonicalSubset, 'invalid_release');
+    return assets;
+  }
+
+  private async bytes(urlArg: string, sizeArg: number, signalArg?: AbortSignal): Promise<Uint8Array> {
+    requireBundle(Number.isSafeInteger(sizeArg) && sizeArg > 0 && sizeArg <= metadataLimit, 'invalid_release');
+    return await this.request(urlArg, signalArg, this.requestTimeoutMs, async (response, signal) => {
+      const chunks: Uint8Array[] = [];
+      await this.consume(response, sizeArg, signal, async (chunk) => { chunks.push(chunk.slice()); }, sizeArg);
+      return Buffer.concat(chunks);
+    });
+  }
+
+  private async json(urlArg: string, signalArg?: AbortSignal, absentReleaseIsPendingArg = false): Promise<unknown> {
+    return await this.request(urlArg, signalArg, this.requestTimeoutMs, async (response, signal) => {
+      const chunks: Uint8Array[] = [];
+      await this.consume(response, 1024 * 1024, signal, async (chunk) => { chunks.push(chunk.slice()); });
+      try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))); }
+      catch { throw new PalletBundleError('invalid_release'); }
+    }, absentReleaseIsPendingArg ? 'release_pending' : undefined);
+  }
+
+  private url(urlArg: string): URL {
+    let url: URL;
+    try { url = new URL(urlArg); } catch { throw new PalletBundleError('invalid_release'); }
+    requireBundle(url.origin === this.origin && !url.username && !url.password && !url.hash, 'invalid_release');
+    return url;
+  }
+
+  private async request<TResult>(urlArg: string, signalArg: AbortSignal | undefined, timeoutArg: number,
+    consumeArg: (responseArg: Response, signalArg: AbortSignal) => Promise<TResult>,
+    notFoundCodeArg?: 'release_pending'): Promise<TResult> {
+    if (signalArg?.aborted) throw new PalletBundleError('aborted');
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signalArg?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, timeoutArg);
+    let response: Response | undefined;
+    try {
+      let url = this.url(urlArg);
+      for (let count = 0; count <= 3; count++) {
+        response = await this.fetchOwner(url, {
+          signal: controller.signal, redirect: 'manual', credentials: 'omit', cache: 'no-store',
+          headers: { 'Accept-Encoding': 'identity' },
+        });
+        if (response.status === 200) return await consumeArg(response, controller.signal);
+        if (response.status === 404 && notFoundCodeArg) throw new PalletBundleError(notFoundCodeArg);
+        const location = response.headers.get('location');
+        requireBundle([301, 302, 303, 307, 308].includes(response.status) && location && count < 3, 'request_failed');
+        await response.body?.cancel();
+        response = undefined;
+        url = this.url(new URL(location, url).href);
+      }
+      throw new PalletBundleError('request_failed');
+    } catch (error) {
+      if (signalArg?.aborted) throw new PalletBundleError('aborted', { cause: error });
+      if (controller.signal.aborted) throw new PalletBundleError('timeout', { cause: error });
+      if (error instanceof PalletBundleError) throw error;
+      throw new PalletBundleError('request_failed', { cause: error });
+    } finally {
+      try { await response?.body?.cancel(); } catch { /* A fully consumed body is already closed. */ }
+      clearTimeout(timer);
+      signalArg?.removeEventListener('abort', abort);
+    }
+  }
+
+  private async consume(responseArg: Response, limitArg: number, signalArg: AbortSignal,
+    writeArg: (chunkArg: Uint8Array) => Promise<void>, expectedArg?: number): Promise<number> {
+    const length = responseArg.headers.get('content-length');
+    requireBundle(length === null || (/^\d+$/.test(length) && Number(length) <= limitArg &&
+      (expectedArg === undefined || Number(length) === expectedArg)), 'invalid_download');
+    requireBundle(responseArg.body, 'invalid_download');
+    const reader = responseArg.body.getReader();
+    let size = 0;
+    try {
+      for (;;) {
+        signalArg.throwIfAborted();
+        const next = await reader.read();
+        if (next.done) break;
+        size += next.value.length;
+        requireBundle(size <= limitArg, 'invalid_download');
+        await writeArg(next.value);
+      }
+      requireBundle(expectedArg === undefined || size === expectedArg, 'invalid_download');
+      return size;
+    } finally {
+      try { await reader.cancel(); } finally { reader.releaseLock(); }
+    }
+  }
+}

package/ts_bundle/errors.ts

@@ -0,0 +1,40 @@
+/** Why a Pallet control bundle, its release or its installed files were refused. */
+export type TPalletBundleErrorCode =
+  /** The caller's own input is malformed (a pin, a target, an option). */
+  | 'invalid_options'
+  /** The pin names another Pallet version than this package's own. */
+  | 'version_mismatch'
+  /** The release is not published yet, or not with all of its assets. */
+  | 'release_pending'
+  /** The release, its metadata or its bundle is not the pinned Pallet control bundle. */
+  | 'invalid_release'
+  /** A request failed, was redirected off the origin or answered an unexpected status. */
+  | 'request_failed'
+  /** A download or request exceeded its deadline. */
+  | 'timeout'
+  /** The caller's signal aborted the operation. */
+  | 'aborted'
+  /** A path is not a canonical, protected location, or it changed while in use. */
+  | 'unsafe_path'
+  /** A download answered other bytes than its release asset states. */
+  | 'invalid_download'
+  /** An executable or file does not carry the digest the bundle states. */
+  | 'artifact_mismatch';
+
+export class PalletBundleError extends Error {
+  /**
+   * Set for `release_pending` when the release exists but does not carry these assets yet; absent
+   * when the release itself is not published yet.
+   */
+  public readonly missingAssets?: readonly string[];
+
+  constructor(public readonly code: TPalletBundleErrorCode, detailsArg: { missingAssets?: readonly string[]; cause?: unknown } = {}) {
+    super(`Pallet control bundle refused: ${code}.`, detailsArg.cause === undefined ? undefined : { cause: detailsArg.cause });
+    this.name = 'PalletBundleError';
+    if (detailsArg.missingAssets) this.missingAssets = Object.freeze([...detailsArg.missingAssets]);
+  }
+}
+
+export function requireBundle(valueArg: unknown, codeArg: TPalletBundleErrorCode): asserts valueArg {
+  if (!valueArg) throw new PalletBundleError(codeArg);
+}

package/ts_bundle/index.ts

@@ -0,0 +1,10 @@
+export * from './errors.js';
+export * from './inventory.js';
+export * from './protocol.js';
+export { palletBundleVersion } from './version.js';
+export { verifyExecutable } from './paths.js';
+export * from './verify.js';
+export * from './classes.releaseclient.js';
+export * from './units.js';
+export * from './classes.controlstderr.js';
+export * from './classes.controlprocess.js';

package/ts_bundle/inventory.ts

@@ -0,0 +1,104 @@
+import * as plugins from './plugins.js';
+
+/**
+ * What a Pallet control bundle is made of, stated once.
+ *
+ * Pallet's own build (`scripts/build-control.mjs`) writes its control record with these paths and
+ * keys, and its packaging (`scripts/control-package.mjs`) runs this package's verifier over every
+ * build before sealing it, so a bundle that disagrees with this description is never released. The
+ * files of each component (clock, DNS, VPN, containerd, notices and sources) are not listed here:
+ * the bundle states them itself in its control record and in the manifests of those components,
+ * and the verifier checks every file against them.
+ */
+
+/** The tspack bundle name, the package that builds it and the Gitea repository that releases it. */
+export const palletControlBundleName = 'pallet-control';
+export const palletControlPackageName = '@serve.zone/pallet';
+export const palletControlRepository = 'serve.zone/pallet';
+
+/** The platforms a release carries, as tspack bundle ids. */
+export const palletControlTargets = ['linux-amd64', 'linux-arm64'] as const;
+export type TPalletControlTarget = typeof palletControlTargets[number];
+
+export const isPalletControlTarget = (valueArg: unknown): valueArg is TPalletControlTarget =>
+  palletControlTargets.some((target) => target === valueArg);
+
+/** The tsrust target every native executable of a bundle was built for. */
+export const palletNativeTarget = (targetArg: TPalletControlTarget): string => `${targetArg.replace('-', '_')}_musl`;
+
+/** The fixed host paths a control build compiles in; its control record repeats them. */
+export const palletControlPaths = Object.freeze({
+  /** The node's store, created only by explicit provisioning. */
+  dataRoot: '/var/lib/serve.zone/pallet',
+  /** The Cloudly enrollment control socket (`enrollment-serve`, `enrollment-provision`). */
+  socketPath: plugins.interfaces.data.palletNodeEnrollmentContract.socketPath,
+  /** The local controller socket a node bound to a controller on its own host serves. */
+  localControllerSocketPath: plugins.interfaces.data.nodeRuntimeLocalControllerContract.socketPath,
+  /** The CRI socket of Pallet's own containerd, never the host's shared one. */
+  runtimeSocketPath: '/run/pallet/containerd/containerd.sock',
+  /** The uid every Pallet process and every installed file belongs to. */
+  expectedUid: 0,
+});
+
+/** Every key of a bundle's `control-build.json`, and nothing else. */
+export const palletControlRecordKeys = Object.freeze([
+  'packageName', 'version', 'sourceCommit', 'sourceDirty', 'target', 'compiler', 'lockSha256', 'dataRoot',
+  'socketPath', 'runtimeSocketPath', 'expectedUid', 'clockManifestSha256', 'dnsManifestSha256',
+  'vpnInventorySha256', 'containerdManifestSha256', 'files',
+] as const);
+
+export const palletControlRecordName = 'control-build.json';
+
+export type TPalletControlRole = 'control' | 'store' | 'runtime' | 'guard' | 'dns' | 'vpn';
+
+export interface IPalletControlRoleDescription {
+  /** Bundle-relative path; the control executable finds each sibling by this name. */
+  readonly path: string;
+  /** The tsrust build provenance beside a native executable. The control itself is compiled by Deno. */
+  readonly provenance?: {
+    readonly path: string;
+    readonly projectName: string;
+    readonly binary: string;
+  };
+}
+
+/** The executables `pallet-control` starts by name, each verified against the digest it compiles in. */
+export const palletControlRoles: Readonly<Record<TPalletControlRole, IPalletControlRoleDescription>> = Object.freeze({
+  control: { path: 'pallet-control' },
+  store: { path: 'pallet-smartdb', provenance: { path: 'pallet-smartdb.tsrust-build.json',
+    projectName: '@lossless.org/nosqldb', binary: 'rustdb' } },
+  runtime: { path: 'pallet-runtime', provenance: { path: 'pallet-runtime.tsrust-build.json',
+    projectName: palletControlPackageName, binary: 'pallet' } },
+  guard: { path: 'pallet-guard', provenance: { path: 'pallet-guard.tsrust-build.json',
+    projectName: '@push.rocks/smartnftables', binary: 'smartnftables' } },
+  dns: { path: 'pallet-dns', provenance: { path: 'pallet-dns.tsrust-build.json',
+    projectName: '@push.rocks/smartdns', binary: 'rustdns' } },
+  vpn: { path: 'pallet-vpn', provenance: { path: 'pallet-vpn.tsrust-build.json',
+    projectName: '@push.rocks/smartvpn', binary: 'smartvpn_daemon' } },
+});
+
+/**
+ * The components whose files a manifest inside the bundle lists, and the control record key that
+ * pins that manifest's digest. `listing` components state every file below `directory` by path,
+ * size, SHA-256 and mode; the others are pinned by digest only and their files are declared in the
+ * control record.
+ */
+export const palletControlComponents = Object.freeze({
+  clock: { manifest: 'pallet-clock/manifest.json', recordKey: 'clockManifestSha256', directory: 'pallet-clock/' },
+  containerd: { manifest: 'pallet-containerd/manifest.json', recordKey: 'containerdManifestSha256',
+    directory: 'pallet-containerd/' },
+  dns: { manifest: 'notices/coredns/manifest.json', recordKey: 'dnsManifestSha256', directory: null },
+  vpn: { manifest: 'notices/smartvpn/notices/inventory.json', recordKey: 'vpnInventorySha256', directory: null },
+} as const);
+
+/** Notice trees in the `tsrust.native-notices` format: a manifest naming every file below it. */
+export const palletControlNoticeTrees = Object.freeze(['native-notices/', 'notices/smartnftables/'] as const);
+
+/**
+ * Notice and corresponding-source inventories: a manifest whose `files` list every file below both
+ * prefixes by path, size and SHA-256.
+ */
+export const palletControlSourceInventories = Object.freeze([
+  { manifest: 'notices/clock/manifest.json', prefixes: ['notices/clock/', 'sources/clock/'] },
+  { manifest: 'notices/containerd/manifest.json', prefixes: ['notices/containerd/', 'sources/containerd/'] },
+] as const);

package/ts_bundle/paths.ts

@@ -0,0 +1,74 @@
+import * as plugins from './plugins.js';
+import { PalletBundleError } from './errors.js';
+
+/** An absolute, normalized path without a trailing slash; `/` itself is refused. */
+export function canonicalPath(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || valueArg.length > 4096 || valueArg.includes('\0') ||
+    !plugins.path.isAbsolute(valueArg) || valueArg === '/' || plugins.path.normalize(valueArg) !== valueArg ||
+    valueArg.endsWith('/')) {
+    throw new PalletBundleError('invalid_options');
+  }
+  return valueArg;
+}
+
+const unsafe = (): never => { throw new PalletBundleError('unsafe_path'); };
+
+/** No symlink ancestor, foreign owner or group/other writer can replace the protected leaf. */
+export async function checkAncestors(pathArg: string, uidArg: number): Promise<void> {
+  let current = plugins.path.dirname(pathArg);
+  for (;;) {
+    const info = await plugins.fs.lstat(current);
+    const rootSticky = info.uid === 0 && (info.mode & 0o1000) !== 0;
+    if (!info.isDirectory() || info.isSymbolicLink() || (info.uid !== uidArg && info.uid !== 0) ||
+      ((info.mode & 0o022) !== 0 && !rootSticky)) unsafe();
+    if (current === '/') return;
+    current = plugins.path.dirname(current);
+  }
+}
+
+const checkExecutable = (infoArg: { isFile(): boolean; isSymbolicLink(): boolean; uid: number; nlink: number; mode: number },
+  uidArg: number): void => {
+  if (!infoArg.isFile() || infoArg.isSymbolicLink() || infoArg.uid !== uidArg || infoArg.nlink !== 1 ||
+    (infoArg.mode & 0o6022) !== 0 || (infoArg.mode & 0o100) === 0) unsafe();
+};
+
+/**
+ * Proves the executable at a protected path carries the digest trusted metadata states. The file is
+ * read through one descriptor opened without following links, and its identity must not change
+ * while it is read.
+ */
+export async function verifyExecutable(pathArg: string, digestArg: string, uidArg: number,
+  signalArg?: AbortSignal): Promise<void> {
+  signalArg?.throwIfAborted();
+  await checkAncestors(pathArg, uidArg);
+  checkExecutable(await plugins.fs.lstat(pathArg), uidArg);
+  const file = await plugins.fs.open(pathArg, plugins.fsConstants.O_RDONLY | plugins.fsConstants.O_NOFOLLOW);
+  try {
+    const before = await file.stat();
+    checkExecutable(before, uidArg);
+    if (before.size < 1 || before.size > 1024 ** 3) unsafe();
+    const hash = plugins.crypto.createHash('sha256');
+    const buffer = Buffer.alloc(1024 * 1024);
+    let position = 0;
+    while (position < before.size) {
+      signalArg?.throwIfAborted();
+      const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, before.size - position), position);
+      if (bytesRead === 0) unsafe();
+      hash.update(buffer.subarray(0, bytesRead));
+      position += bytesRead;
+    }
+    const after = await file.stat();
+    if (after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs ||
+      after.ino !== before.ino || after.dev !== before.dev) unsafe();
+    if (hash.digest('hex') !== digestArg) throw new PalletBundleError('artifact_mismatch');
+  } finally {
+    await file.close();
+  }
+}
+
+/** A directory that is canonical (its real path is itself) and a directory. */
+export async function requireCanonicalDirectory(pathArg: string): Promise<void> {
+  canonicalPath(pathArg);
+  const info = await plugins.fs.lstat(pathArg).catch(() => unsafe());
+  if (!info.isDirectory() || await plugins.fs.realpath(pathArg) !== pathArg) unsafe();
+}

package/ts_bundle/plugins.ts

@@ -0,0 +1,25 @@
+// node native scope
+import * as childProcess from 'node:child_process';
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import * as nodeUtil from 'node:util';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export { childProcess, crypto, fs, fsConstants, nodeUtil, os, path };
+
+// @git.zone scope
+import * as tspack from '@git.zone/tspack';
+
+export { tspack };
+
+// @push.rocks scope
+import * as smartdaemon from '@push.rocks/smartdaemon';
+
+export { smartdaemon };
+
+// @serve.zone scope
+import * as interfaces from '@serve.zone/interfaces';
+
+export { interfaces };

package/ts_bundle/protocol.ts

@@ -0,0 +1,56 @@
+/**
+ * The process protocol of `pallet-control`: its modes, the protocol each mode reports on standard
+ * output and the reasons a `failed` line names. `pallet-control` itself reports with these names
+ * (`ts/control/process-cli.ts`), and the supervisors in this package read them. This module has no
+ * dependencies, so the compiled control can import it.
+ */
+
+/** Every line of the protocol starts with this prefix, followed by one JSON object. */
+export const palletControlLinePrefix = 'PALLET_CONTROL ';
+
+export const palletControlProtocols = Object.freeze({
+  enrollment: 'pallet.enrollment.process',
+  node: 'pallet.node.process',
+  guard: 'pallet.guard.process',
+  acquisition: 'pallet.network.acquisition',
+  containerd: 'pallet.containerd.process',
+  storageImport: 'pallet.storage.import',
+  storeProvision: 'pallet.store.provision',
+} as const);
+
+/**
+ * Modes a supervisor holds for its lifetime through a stdin pipe: the child stops when that pipe
+ * closes. `runtime-serve` is the node process as a supervised child.
+ */
+export const palletControlLifetimeModes = Object.freeze({
+  'enrollment-serve': palletControlProtocols.enrollment,
+  'enrollment-provision': palletControlProtocols.enrollment,
+  'runtime-serve': palletControlProtocols.node,
+} as const);
+export type TPalletControlLifetimeMode = keyof typeof palletControlLifetimeModes;
+
+/** Oneshot modes: null stdin is valid, and `ready` followed by `stopped` is their success. */
+export const palletControlOneshotModes = Object.freeze({
+  'guard-recover': palletControlProtocols.guard,
+  'guard-commission': palletControlProtocols.guard,
+  'network-acquire': palletControlProtocols.acquisition,
+  'network-acquire-local': palletControlProtocols.acquisition,
+  'store-provision': palletControlProtocols.storeProvision,
+} as const);
+export type TPalletControlOneshotMode = keyof typeof palletControlOneshotModes;
+
+/**
+ * Service unit main processes. Their stdin is null and a signal stops them; the service manager,
+ * not a supervisor in this package, runs them.
+ */
+export const palletControlUnitModes = Object.freeze({
+  'containerd-serve': palletControlProtocols.containerd,
+  'runtime-unit': palletControlProtocols.node,
+} as const);
+export type TPalletControlUnitMode = keyof typeof palletControlUnitModes;
+
+/** The reasons a `failed` line names. */
+export const palletControlFailureReasons = Object.freeze([
+  'invalid_arguments', 'invalid_ca_store', 'invalid_stdin', 'owner_failed', 'unsupported_kernel',
+] as const);
+export type TPalletControlFailureReason = typeof palletControlFailureReasons[number];