@dench.com/cli 3.7.0-staging.387 → 3.8.1-staging.390

package/lib/environment-archive.ts

@@ -0,0 +1,255 @@
+import { createHash } from "node:crypto";
+import { chmod, link, mkdir, symlink, writeFile } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+import { gunzipSync } from "node:zlib";
+
+export const MAX_PREPARED_ARCHIVE_BYTES = 128 * 1024 * 1024;
+const MAX_UNPACKED_BYTES = 512 * 1024 * 1024;
+const MAX_ARCHIVE_FILES = 40_000;
+
+export function sha256(bytes: Uint8Array | string): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+function fail(message: string): never {
+  throw new Error(`invalid_environment_artifact: ${message}`);
+}
+
+export async function fetchEnvironmentBytes(
+  url: string,
+  limit: number,
+  expectedHash?: string,
+): Promise<Buffer> {
+  const parsed = new URL(url);
+  if (
+    parsed.protocol !== "https:" &&
+    !(
+      parsed.protocol === "http:" &&
+      ["127.0.0.1", "localhost", "[::1]"].includes(parsed.hostname)
+    )
+  )
+    fail("Artifact URL must use HTTPS.");
+  const response = await fetch(url, {
+    redirect: "error",
+    signal: AbortSignal.timeout(120_000),
+  });
+  if (!response.ok || !response.body)
+    fail(
+      "Artifact download failed; retry preparation, not the business operation.",
+    );
+  const declared = Number(response.headers.get("content-length") ?? 0);
+  if (declared > limit) fail("Artifact exceeds the download limit.");
+  const chunks: Buffer[] = [];
+  let size = 0;
+  const reader = response.body.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > limit) {
+        await reader.cancel();
+        fail("Artifact exceeds the download limit.");
+      }
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = Buffer.concat(chunks);
+  if (expectedHash && sha256(bytes) !== expectedHash)
+    fail("Artifact checksum does not match its saved revision.");
+  return bytes;
+}
+
+function tarString(header: Buffer, start: number, length: number): string {
+  const bytes = header.subarray(start, start + length);
+  return bytes
+    .subarray(0, bytes.indexOf(0) < 0 ? bytes.length : bytes.indexOf(0))
+    .toString("utf8");
+}
+function tarNumber(header: Buffer, start: number, length: number): number {
+  const value = tarString(header, start, length).trim();
+  if (value && !/^[0-7]+$/.test(value))
+    fail("Unsupported tar numeric encoding.");
+  const number = value ? Number.parseInt(value, 8) : 0;
+  if (!Number.isSafeInteger(number) || number < 0) fail("Invalid tar size.");
+  return number;
+}
+function archivePath(raw: string): string {
+  const path = raw.replace(/^(\.\/)+/, "").replace(/\/$/, "");
+  if (
+    !path ||
+    path.length > 1024 ||
+    path.startsWith("/") ||
+    path.includes("\\") ||
+    [...path].some((char) => char.charCodeAt(0) < 32) ||
+    path.split("/").some((p) => !p || p === "." || p === "..")
+  )
+    fail("Archive contains an unsafe path.");
+  return path;
+}
+function parsePax(data: Buffer): Record<string, string> {
+  const output: Record<string, string> = {};
+  let offset = 0;
+  while (offset < data.length) {
+    const space = data.indexOf(32, offset);
+    if (space < 0) fail("Invalid tar metadata.");
+    const rawLength = data.subarray(offset, space).toString("ascii");
+    const length = Number(rawLength);
+    if (
+      !/^\d+$/.test(rawLength) ||
+      length <= space - offset + 1 ||
+      offset + length > data.length
+    )
+      fail("Invalid tar metadata length.");
+    const item = data.subarray(space + 1, offset + length).toString("utf8");
+    const equals = item.indexOf("=");
+    if (equals < 1 || !item.endsWith("\n")) fail("Invalid tar metadata value.");
+    const key = item.slice(0, equals);
+    if (key.startsWith("GNU.sparse") || key === "size")
+      fail("Sparse or extended-size archives are unsupported.");
+    output[key] = item.slice(equals + 1, -1);
+    offset += length;
+  }
+  return output;
+}
+
+type Entry = {
+  path: string;
+  kind: "file" | "dir" | "symlink" | "hardlink";
+  mode: number;
+  content: Buffer;
+  target?: string;
+};
+/** Validate the entire archive before writing anything, including every link ancestor. */
+export function inspectPreparedArchive(compressed: Buffer): Entry[] {
+  if (compressed.length > MAX_PREPARED_ARCHIVE_BYTES)
+    fail("Compressed archive is too large.");
+  const bytes = gunzipSync(compressed, { maxOutputLength: MAX_UNPACKED_BYTES });
+  const entries: Entry[] = [];
+  const seen = new Map<string, Entry>();
+  let pax: Record<string, string> = {};
+  let longName: string | undefined;
+  let longLink: string | undefined;
+  for (let offset = 0; offset + 512 <= bytes.length; ) {
+    const header = bytes.subarray(offset, offset + 512);
+    if (header.every((value) => value === 0)) break;
+    let checksum = 0;
+    for (let i = 0; i < 512; i++)
+      checksum += i >= 148 && i < 156 ? 32 : header[i];
+    if (checksum !== tarNumber(header, 148, 8))
+      fail("Invalid tar header checksum.");
+    const size = tarNumber(header, 124, 12);
+    if (offset + 512 + size > bytes.length) fail("Truncated archive.");
+    const content = bytes.subarray(offset + 512, offset + 512 + size);
+    offset += 512 + Math.ceil(size / 512) * 512;
+    const type = tarString(header, 156, 1);
+    if (type === "x") {
+      pax = parsePax(content);
+      continue;
+    }
+    if (type === "L" || type === "K") {
+      const value = content
+        .toString("utf8")
+        .replace(/\0.*$/, "")
+        .replace(/\n$/, "");
+      if (type === "L") longName = value;
+      else longLink = value;
+      continue;
+    }
+    if (type === "g") fail("Global tar metadata is unsupported.");
+    const prefix = tarString(header, 345, 155);
+    const rawPath =
+      pax.path ??
+      longName ??
+      [prefix, tarString(header, 0, 100)].filter(Boolean).join("/");
+    const rawTarget = pax.linkpath ?? longLink ?? tarString(header, 157, 100);
+    pax = {};
+    longName = undefined;
+    longLink = undefined;
+    if ((rawPath === "." || rawPath === "./") && type === "5") continue;
+    const path = archivePath(rawPath);
+    const kind =
+      type === "" || type === "0"
+        ? "file"
+        : type === "5"
+          ? "dir"
+          : type === "2"
+            ? "symlink"
+            : type === "1"
+              ? "hardlink"
+              : undefined;
+    if (!kind)
+      fail("Only files, directories and internal links are supported.");
+    if (seen.has(path)) fail("Duplicate archive path.");
+    const mode =
+      kind === "dir" || tarNumber(header, 100, 8) & 0o111 ? 0o755 : 0o644;
+    const entry: Entry = { path, kind, mode, content };
+    if (kind === "symlink") {
+      if (
+        !rawTarget ||
+        rawTarget.startsWith("/") ||
+        rawTarget.includes("\\") ||
+        [...rawTarget].some((char) => char.charCodeAt(0) < 32)
+      )
+        fail("Archive symlink must stay inside its environment.");
+      const destination = posix.normalize(
+        posix.join(posix.dirname(path), rawTarget),
+      );
+      if (destination === ".." || destination.startsWith("../"))
+        fail("Archive symlink escapes its environment.");
+      entry.target = rawTarget;
+    } else if (kind === "hardlink") entry.target = archivePath(rawTarget);
+    entries.push(entry);
+    seen.set(path, entry);
+    if (entries.length > MAX_ARCHIVE_FILES) fail("Archive has too many files.");
+  }
+  if (pax.path || longName || longLink)
+    fail("Archive ended in incomplete metadata.");
+  for (const entry of entries) {
+    for (
+      let parent = posix.dirname(entry.path);
+      parent !== ".";
+      parent = posix.dirname(parent)
+    ) {
+      const ancestor = seen.get(parent);
+      if (ancestor && ancestor.kind !== "dir")
+        fail("Archive path traverses a link or file.");
+    }
+    if (
+      entry.kind === "hardlink" &&
+      (!entry.target || seen.get(entry.target)?.kind !== "file")
+    )
+      fail("Hard links must refer to a regular archive file.");
+  }
+  return entries;
+}
+
+export async function extractPreparedArchive(
+  compressed: Buffer,
+  destination: string,
+): Promise<void> {
+  const entries = inspectPreparedArchive(compressed);
+  await mkdir(destination, { recursive: true, mode: 0o700 });
+  for (const entry of entries.filter(
+    (entry) => entry.kind === "dir" || entry.kind === "file",
+  )) {
+    const path = join(destination, entry.path);
+    await mkdir(dirname(path), { recursive: true, mode: 0o755 });
+    if (entry.kind === "dir")
+      await mkdir(path, { recursive: true, mode: entry.mode });
+    else {
+      await writeFile(path, entry.content, { mode: entry.mode, flag: "wx" });
+      await chmod(path, entry.mode);
+    }
+  }
+  for (const entry of entries.filter(
+    (entry) => entry.kind === "symlink" || entry.kind === "hardlink",
+  )) {
+    const path = join(destination, entry.path);
+    await mkdir(dirname(path), { recursive: true, mode: 0o755 });
+    if (!entry.target) fail("Archive link has no destination.");
+    if (entry.kind === "symlink") await symlink(entry.target, path);
+    else await link(join(destination, entry.target), path);
+  }
+}

package/lib/environment-cli-args.ts

@@ -0,0 +1,96 @@
+import { CliArgError } from "./cli-args";
+import { validateSecretName } from "./environment-contract";
+
+/** Parse only this command's options; everything after -- belongs to the child. */
+export function parseEnvironmentOptions(
+  input: readonly string[],
+  values: readonly string[],
+  booleans: readonly string[] = [],
+): {
+  positional: string[];
+  flags: Record<string, string | boolean>;
+  child: string[];
+} {
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  let child: string[] = [];
+  for (let i = 0; i < input.length; i++) {
+    const arg = input[i];
+    if (arg === "--") {
+      child = input.slice(i + 1);
+      break;
+    }
+    if (!arg.startsWith("-")) {
+      positional.push(arg);
+      continue;
+    }
+    if (!(values.includes(arg) || booleans.includes(arg))) {
+      throw new CliArgError(
+        `Unknown flag: ${arg}. Use --help for supported options.`,
+      );
+    }
+    if (Object.hasOwn(flags, arg))
+      throw new CliArgError(`Duplicate flag: ${arg}`);
+    if (booleans.includes(arg)) {
+      flags[arg] = true;
+      continue;
+    }
+    const value = input[++i];
+    if (!value || value.startsWith("-"))
+      throw new CliArgError(`${arg} requires a value.`);
+    flags[arg] = value;
+  }
+  return { positional, flags, child };
+}
+
+export function isEnvironmentHelp(args: readonly string[]): boolean {
+  const boundary = args.indexOf("--");
+  return (
+    args
+      .slice(0, boundary < 0 ? undefined : boundary)
+      .some((arg) => arg === "--help" || arg === "-h") ||
+    args[0] === "help" ||
+    args.length === 0
+  );
+}
+
+export function requireEnvironmentName(value: string | undefined): string {
+  if (!value || !/^[a-z][a-z0-9-]{0,63}$/.test(value)) {
+    throw new CliArgError(
+      "Environment name must use lowercase letters, numbers and hyphens (1–64 characters), beginning with a letter.",
+    );
+  }
+  return value;
+}
+
+export function requireSecretName(value: string | undefined): string {
+  if (!value || !/^[A-Z][A-Z0-9_]{0,127}$/.test(value)) {
+    throw new CliArgError(
+      "Secret name must use uppercase letters, numbers and underscores (1–128 characters).",
+    );
+  }
+  return validateSecretName(value);
+}
+
+export function integerOption(
+  value: string | boolean | undefined,
+  name: string,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (
+    typeof value !== "string" ||
+    !/^\d+$/.test(value) ||
+    !Number.isSafeInteger(parsed) ||
+    parsed < min ||
+    parsed > max
+  ) {
+    throw new CliArgError(
+      `${name} must be an integer between ${min} and ${max}.`,
+    );
+  }
+  return parsed;
+}

package/lib/environment-contract.ts

@@ -0,0 +1,237 @@
+/** Shared, side-effect-free saved-environment wire contract. */
+export const ENVIRONMENT_MANIFEST_FILE = "dench-env.json";
+export const MAX_ENVIRONMENT_SOURCE_BYTES = 16 * 1024 * 1024;
+export const MAX_ENVIRONMENT_PREPARED_BYTES = 128 * 1024 * 1024;
+export const MAX_ENVIRONMENT_FILES = 512;
+export const MAX_WORKSPACE_SECRET_BYTES = 64 * 1024;
+export const ENVIRONMENT_NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+export const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]{0,127}$/;
+
+export type EnvironmentManifest = {
+  version: 1;
+  name: string;
+  purpose: string;
+  files: string[];
+  prepare: string[];
+  verify: string[];
+  env: Record<string, string>;
+  secretEnv: Record<string, string>;
+  secretFiles: { path: string; secret: string; mutable?: boolean }[];
+  statePaths: string[];
+  portable: boolean;
+};
+export type EnvironmentSourceBundle = {
+  version: 1;
+  files: { path: string; contentBase64: string; mode: 420 | 493 }[];
+};
+export type EnvironmentArtifacts = {
+  snapshotId?: string;
+  bundleStorageId?: string;
+  bundleSha256?: string;
+  bundleBytes?: number;
+  prefix: string;
+  runtimeAbi: string;
+  platform: "linux/amd64" | "linux/arm64";
+  verifiedAt: number;
+};
+export type EnvironmentRevision = {
+  id: string;
+  name: string;
+  revision: string;
+  status: "pending" | "building" | "ready" | "failed";
+  manifest: EnvironmentManifest;
+  source: { storageId: string; sha256: string; size: number };
+  sourcePrefix: string;
+  artifacts?: EnvironmentArtifacts;
+  errorCode?: string;
+  createdAt: number;
+};
+
+function fail(message: string): never {
+  throw new Error(`validation_failed: ${message}`);
+}
+export function validateEnvironmentName(value: string): string {
+  if (!ENVIRONMENT_NAME_PATTERN.test(value))
+    fail("Environment name must be a lowercase slug of at most 64 characters.");
+  return value;
+}
+export function validateSecretName(value: string): string {
+  if (!SECRET_NAME_PATTERN.test(value))
+    fail("Secret names must use uppercase letters, digits and underscores.");
+  if (
+    /^(DENCH_|HARNESS_|CONVEX_|VERCEL_|DAYTONA_|NODE_OPTIONS$|NODE_PATH$|LD_|DYLD_|PATH$|HOME$|SHELL$|BASH_ENV$|ENV$|PYTHONPATH$|PYTHONHOME$)/.test(
+      value,
+    )
+  )
+    fail("Platform and process-control environment names are reserved.");
+  return value;
+}
+export function validateEnvironmentPath(value: string): string {
+  if (
+    !value ||
+    value.length > 512 ||
+    value.startsWith("/") ||
+    value.includes("\\") ||
+    [...value].some((character) => character.charCodeAt(0) < 32) ||
+    value.split("/").some((part) => !part || part === "." || part === "..")
+  )
+    fail(
+      "Environment paths must be normalized relative paths without traversal.",
+    );
+  return value;
+}
+export function isForbiddenEnvironmentSourcePath(value: string): boolean {
+  return value
+    .split("/")
+    .some((part) =>
+      /^(\.env(?:\..*)?|\.npmrc|\.pypirc|\.netrc|\.ssh|\.aws|\.config|\.git|node_modules|__pycache__|\.venv|credentials(?:\..*)?)$/i.test(
+        part,
+      ),
+    );
+}
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    fail(`${label} must be an object.`);
+  return value as Record<string, unknown>;
+}
+function strings(value: unknown, label: string, max = 64): string[] {
+  if (
+    !Array.isArray(value) ||
+    value.length > max ||
+    value.some((x) => typeof x !== "string" || !x || x.length > 8192)
+  )
+    fail(`${label} must be a bounded list of nonempty strings.`);
+  return value as string[];
+}
+export function parseEnvironmentManifest(value: unknown): EnvironmentManifest {
+  const input = record(value, "Manifest");
+  const keys = new Set([
+    "version",
+    "name",
+    "purpose",
+    "files",
+    "prepare",
+    "verify",
+    "env",
+    "secretEnv",
+    "secretFiles",
+    "statePaths",
+    "portable",
+  ]);
+  if (Object.keys(input).some((key) => !keys.has(key)))
+    fail("Unknown environment manifest field.");
+  if (
+    input.version !== 1 ||
+    typeof input.name !== "string" ||
+    typeof input.purpose !== "string" ||
+    !input.purpose.trim() ||
+    input.purpose.length > 2000
+  )
+    fail("Manifest requires version 1, name and purpose.");
+  validateEnvironmentName(input.name);
+  const files = strings(input.files, "files", MAX_ENVIRONMENT_FILES);
+  for (const path of files) {
+    validateEnvironmentPath(path);
+    if (isForbiddenEnvironmentSourcePath(path))
+      fail("Credential/cache paths cannot be saved as source files.");
+  }
+  const map = (raw: unknown, label: string, secret: boolean) => {
+    const values = record(raw ?? {}, label);
+    if (Object.keys(values).length > 64)
+      fail(`${label} has too many bindings.`);
+    const result: Record<string, string> = {};
+    for (const [key, val] of Object.entries(values)) {
+      validateSecretName(key);
+      if (
+        !secret &&
+        /(?:^|_)(?:API_KEY|ACCESS_KEY|PRIVATE_KEY|SECRET|TOKEN|PASSWORD|CREDENTIALS?)(?:_|$)/.test(
+          key,
+        )
+      )
+        fail(
+          "Credential-looking variables must use secretEnv bindings, never public env values.",
+        );
+      if (typeof val !== "string" || val.length > 8192)
+        fail(`${label} values must be strings of at most 8192 characters.`);
+      if (secret) validateSecretName(val);
+      result[key] = val;
+    }
+    return result;
+  };
+  const secretFilesRaw = input.secretFiles ?? [];
+  if (!Array.isArray(secretFilesRaw) || secretFilesRaw.length > 32)
+    fail("secretFiles must be a bounded list.");
+  const secretFiles = secretFilesRaw.map((item) => {
+    const binding = record(item, "secretFiles binding");
+    if (
+      Object.keys(binding).some(
+        (key) => !["path", "secret", "mutable"].includes(key),
+      ) ||
+      typeof binding.path !== "string" ||
+      typeof binding.secret !== "string" ||
+      (binding.mutable !== undefined && typeof binding.mutable !== "boolean")
+    )
+      fail("Invalid secretFiles binding.");
+    return {
+      path: validateEnvironmentPath(binding.path as string),
+      secret: validateSecretName(binding.secret as string),
+      ...(binding.mutable !== undefined
+        ? { mutable: binding.mutable as boolean }
+        : {}),
+    };
+  });
+  const statePaths = strings(input.statePaths ?? [], "statePaths", 32).map(
+    validateEnvironmentPath,
+  );
+  const output: EnvironmentManifest = {
+    version: 1,
+    name: input.name,
+    purpose: input.purpose.trim(),
+    files,
+    prepare: strings(input.prepare ?? [], "prepare", 32),
+    verify: strings(input.verify ?? [], "verify", 32),
+    env: map(input.env, "env", false),
+    secretEnv: map(input.secretEnv, "secretEnv", true),
+    secretFiles,
+    statePaths,
+    portable: input.portable !== false,
+  };
+  if (input.portable !== undefined && typeof input.portable !== "boolean")
+    fail("portable must be a boolean.");
+  if (!output.verify.length)
+    fail("At least one verification command is required before publication.");
+  if (Object.keys(output.env).some((key) => key in output.secretEnv))
+    fail("A variable cannot be both public and secret.");
+  const destinations = [
+    ...secretFiles.map((binding) => binding.path),
+    ...statePaths,
+  ];
+  if (new Set(destinations).size !== destinations.length)
+    fail("Secret/state destinations must be distinct.");
+  if (
+    destinations.some((path, index) =>
+      destinations.some(
+        (other, otherIndex) =>
+          index !== otherIndex && path.startsWith(`${other}/`),
+      ),
+    )
+  )
+    fail("Secret and state paths must not contain one another.");
+  if (JSON.stringify(output).length > 64 * 1024) fail("Manifest is too large.");
+  return output;
+}
+
+export function environmentRequiredSecrets(
+  manifest: EnvironmentManifest,
+): string[] {
+  return [
+    ...new Set([
+      ...Object.values(manifest.secretEnv),
+      ...manifest.secretFiles.map((item) => item.secret),
+    ]),
+  ].sort();
+}
+export function environmentPrefix(revision: string): string {
+  if (!/^[a-f0-9]{64}$/.test(revision)) fail("Invalid environment revision.");
+  return `/opt/dench/environments/${revision}`;
+}