@untangle-code/cli 0.0.0-stage → 0.1.0

package/src/commands/extensions/setup.ts

@@ -0,0 +1,140 @@
+/** Runs a user-supplied setup provider after consent, ownership and digest checks. */
+import type { ExtensionManifestV1 } from "@untangle-code/domain";
+import {
+  isLoopbackUrl,
+  type ProcessLimitsV1,
+  type ProcessRunnerPort,
+} from "@untangle-code/extension-runtime";
+
+import type { ExtensionEnvironmentV1 } from "./environment.js";
+import { primaryHostPort, type ProvisionResultV1 } from "./provision.js";
+import {
+  credentialEndpoint,
+  parseSecretValues,
+  readStoredSecrets,
+  secretEnvironment,
+  withSecretLock,
+  writeStoredSecrets,
+} from "./secret-store.js";
+
+export function missingAnalyzerSecrets(
+  manifest: ExtensionManifestV1,
+  env: Readonly<Record<string, string | undefined>>,
+): string[] {
+  return manifest.secrets
+    .filter(
+      (secret) =>
+        !secret.setupOnly &&
+        (secret.required || secret.name === manifest.http?.authSecretName) &&
+        !env[secret.envVar],
+    )
+    .map((secret) => secret.name);
+}
+
+export async function setupCredentials(input: {
+  environment: ExtensionEnvironmentV1;
+  manifest: ExtensionManifestV1;
+  provision?: ProvisionResultV1;
+  consent: boolean;
+  url?: string;
+  processRunner: ProcessRunnerPort;
+  limits: ProcessLimitsV1;
+  signal?: AbortSignal;
+}): Promise<Record<string, string | undefined>> {
+  const { environment, manifest, provision } = input;
+  const setup = manifest.setup;
+  if (!input.consent) throw new Error("Credential setup requires --yes.");
+  if (
+    !setup ||
+    !manifest.container ||
+    !provision?.healthy ||
+    !provision.state.running ||
+    !provision.state.ownedByUntangle ||
+    provision.state.imageDigest !== manifest.container.digest
+  ) {
+    throw new Error(
+      "Credential setup requires a healthy, owned container whose digest matches the manifest.",
+    );
+  }
+  const url = input.url ?? manifest.http?.defaultUrl;
+  if (
+    !url ||
+    !isLoopbackUrl(url) ||
+    credentialEndpoint(url) !== credentialEndpoint(manifest.http?.defaultUrl)
+  ) {
+    throw new Error(
+      "Credential setup only uses the declared loopback endpoint of the managed container.",
+    );
+  }
+  const endpoint = new URL(url);
+  if (
+    Number(endpoint.port || (endpoint.protocol === "https:" ? 443 : 80)) !==
+    primaryHostPort(manifest)
+  ) {
+    throw new Error("Credential setup endpoint must match the managed container's published port.");
+  }
+  return withSecretLock(environment, manifest.id, async () => {
+    input.signal?.throwIfAborted();
+    const stored = await readStoredSecrets(environment, manifest, url);
+    const effectiveEnv = secretEnvironment(environment, manifest, stored);
+    if (missingAnalyzerSecrets(manifest, effectiveEnv).length === 0) return effectiveEnv;
+    const env: Record<string, string> = {
+      PATH: environment.env["PATH"] ?? "",
+      UNTANGLE_SETUP_URL: url,
+      UNTANGLE_SETUP_ID: manifest.id,
+    };
+    for (const name of ["HOME", "LANG"]) {
+      const value = environment.env[name];
+      if (value !== undefined) env[name] = value;
+    }
+    for (const secret of manifest.secrets) {
+      const value = effectiveEnv[secret.envVar];
+      if (value) env[secret.envVar] = value;
+    }
+    const result = await input.processRunner.run(
+      {
+        command: setup.command,
+        args: setup.args,
+        cwd: environment.userDataDir,
+        env,
+      },
+      {
+        ...input.limits,
+        timeoutMs: Math.min(input.limits.timeoutMs, 120_000),
+        maxOutputBytes: 1_048_576,
+      },
+      input.signal === undefined ? {} : { signal: input.signal },
+    );
+    input.signal?.throwIfAborted();
+    // Neither stdout nor stderr may appear in diagnostics: both can contain freshly issued secrets.
+    if (result.outcome !== "completed" || result.exitCode !== 0 || result.stdoutTruncated) {
+      throw new Error(
+        `Credential setup provider failed (${result.outcome}, exit ${String(result.exitCode)}). Check the configured administrator credentials and service availability.`,
+      );
+    }
+    let response: unknown;
+    try {
+      response = JSON.parse(result.stdout);
+    } catch {
+      throw new Error("Credential setup provider returned invalid JSON; output was withheld.");
+    }
+    if (
+      response === null ||
+      typeof response !== "object" ||
+      !("schemaVersion" in response) ||
+      response.schemaVersion !== 1 ||
+      !("secrets" in response)
+    ) {
+      throw new Error(
+        "Credential setup provider must return schemaVersion 1 and declared secrets; output was withheld.",
+      );
+    }
+    const generated = parseSecretValues(response.secrets, manifest);
+    const combined = { ...stored, ...generated };
+    const resolved = secretEnvironment(environment, manifest, combined);
+    if (missingAnalyzerSecrets(manifest, resolved).length > 0)
+      throw new Error("Credential setup provider did not supply the required analyzer secrets.");
+    await writeStoredSecrets(environment, manifest, combined, url);
+    return resolved;
+  });
+}

package/src/commands/extensions/source.ts

@@ -0,0 +1,189 @@
+/**
+ * Where an `add` gets its manifest from, and what it must prove first.
+ *
+ * A manifest is a description of how to start a program. Fetching one over
+ * the network and writing it into the user profile is therefore a supply-chain
+ * step, and it is treated like one:
+ *
+ * - **https only.** Plain http would let anyone on the path replace the
+ *   invocation. There is no `--insecure` escape hatch; a local copy plus
+ *   `--from <path>` is the supported answer for an internal http host.
+ * - **`--digest` is mandatory for a URL.** Without it, "the file at this URL"
+ *   is not a fixed artifact — it is whatever the server serves today. This is
+ *   the same reason X6 forbids moving image tags: an artifact that can change
+ *   under a stable name changes findings silently.
+ * - **A size ceiling.** A manifest is a small TOML file; an endless response
+ *   must not become an endless allocation.
+ *
+ * The digest is sha256 over the RAW BYTES, which is exactly what
+ * `shasum -a 256 <file>` and `sha256sum <file>` print — so the value a
+ * publisher advertises can be verified by hand.
+ */
+import { createHash } from "node:crypto";
+
+import type { FileSystemPort } from "@untangle-code/domain";
+import { MANIFEST_FILE_NAME } from "@untangle-code/extension-runtime";
+
+/** Largest manifest this CLI will accept from a URL. */
+export const MAX_MANIFEST_BYTES = 256 * 1024;
+
+/** Network read budget for one manifest fetch. */
+export const FETCH_TIMEOUT_MS = 30_000;
+
+export const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+export interface ManifestSourceV1 {
+  kind: "path" | "url";
+  /** What the user typed, for the report. */
+  requested: string;
+  /** Absolute path or final URL the bytes actually came from. */
+  resolved: string;
+  bytes: Uint8Array;
+  text: string;
+  /** `sha256:<64 hex>` over `bytes`. */
+  digest: string;
+}
+
+export class ManifestSourceError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "ManifestSourceError";
+  }
+}
+
+/** True when the argument looks like a URL rather than a path. */
+export function isUrlSource(from: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(from);
+}
+
+export function digestOf(bytes: Uint8Array): string {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+export interface FetchManifestOptions {
+  /** Injected so unit tests never touch the network (CONTRIBUTING, §13). */
+  fetchImpl?: typeof fetch;
+  maxBytes?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * Reads a manifest from a local path.
+ *
+ * `path` may be the manifest file or the directory containing it; the same
+ * convenience `loadExtensionFrom` offers, applied to the raw bytes so the
+ * digest is computed over the file that will actually be installed.
+ */
+export async function readManifestFromPath(
+  fs: FileSystemPort,
+  path: string,
+): Promise<ManifestSourceV1> {
+  const stat = await fs.stat(path);
+  if (stat === null) {
+    throw new ManifestSourceError(`no such file or directory: "${path}"`);
+  }
+  const filePath = stat.kind === "directory" ? `${path}/${MANIFEST_FILE_NAME}` : path;
+  let bytes: Uint8Array;
+  try {
+    bytes = await fs.readFile(filePath);
+  } catch (cause) {
+    throw new ManifestSourceError(
+      `cannot read "${filePath}": ${cause instanceof Error ? cause.message : String(cause)}`,
+    );
+  }
+  return {
+    kind: "path",
+    requested: path,
+    resolved: filePath,
+    bytes,
+    text: new TextDecoder("utf-8", { fatal: false }).decode(bytes),
+    digest: digestOf(bytes),
+  };
+}
+
+/**
+ * Downloads a manifest over https.
+ *
+ * Redirects are followed but the FINAL url is reported, so a redirect never
+ * hides where the bytes came from. The mandatory `--digest` check happens in
+ * the caller, against whatever this returns.
+ */
+export async function fetchManifestFromUrl(
+  url: string,
+  options: FetchManifestOptions = {},
+): Promise<ManifestSourceV1> {
+  const parsed = safeParseUrl(url);
+  if (parsed === null) {
+    throw new ManifestSourceError(`"${url}" is not a valid URL`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new ManifestSourceError(
+      `refusing to download a manifest over "${parsed.protocol}//" — ` +
+        "a manifest describes how to start a program, so the transport must be authenticated. " +
+        "Download it yourself and install the local copy with --from <path>",
+    );
+  }
+
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const maxBytes = options.maxBytes ?? MAX_MANIFEST_BYTES;
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, options.timeoutMs ?? FETCH_TIMEOUT_MS);
+  options.signal?.addEventListener("abort", () => {
+    controller.abort();
+  });
+
+  try {
+    const response = await fetchImpl(parsed.toString(), {
+      redirect: "follow",
+      signal: controller.signal,
+      headers: { accept: "text/plain, application/toml, */*" },
+    });
+    if (!response.ok) {
+      throw new ManifestSourceError(
+        `${parsed.toString()} answered HTTP ${String(response.status)}; no manifest was installed`,
+      );
+    }
+    const buffer = new Uint8Array(await response.arrayBuffer());
+    if (buffer.byteLength > maxBytes) {
+      throw new ManifestSourceError(
+        `the response is ${String(buffer.byteLength)} bytes, above the ${String(maxBytes)}-byte ` +
+          "ceiling for a manifest; nothing was installed",
+      );
+    }
+    const resolved =
+      typeof response.url === "string" && response.url !== "" ? response.url : parsed.toString();
+    return {
+      kind: "url",
+      requested: url,
+      resolved,
+      bytes: buffer,
+      text: new TextDecoder("utf-8", { fatal: false }).decode(buffer),
+      digest: digestOf(buffer),
+    };
+  } catch (cause) {
+    if (cause instanceof ManifestSourceError) {
+      throw cause;
+    }
+    if (controller.signal.aborted) {
+      throw new ManifestSourceError(
+        `downloading ${parsed.toString()} exceeded the ${String(options.timeoutMs ?? FETCH_TIMEOUT_MS)} ms budget`,
+      );
+    }
+    throw new ManifestSourceError(
+      `cannot download ${parsed.toString()}: ${cause instanceof Error ? cause.message : String(cause)}`,
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function safeParseUrl(url: string): URL | null {
+  try {
+    return new URL(url);
+  } catch {
+    return null;
+  }
+}

package/src/commands/extensions/state.ts

@@ -0,0 +1,252 @@
+/**
+ * Persisted user-level state for the extension surface.
+ *
+ * Two files, both in the OS user data directory and never in a project
+ * directory (extensions.md §9.2):
+ *
+ * - `license-acknowledgments.json` — the personal declarations that satisfy
+ *   the license gate. Read by the runtime, written here.
+ * - `cli-state.json` — which extensions the user enabled, and a summary of
+ *   the last run per extension, so `list` can answer "status, last run"
+ *   without re-running anything.
+ *
+ * Both are written temp-then-rename. A half-written acknowledgment file would
+ * read back as "nothing acknowledged", which is safe, but a half-written run
+ * record would silently lose the previous one.
+ */
+import { dirname, join } from "node:path";
+
+import type { FileSystemPort } from "@untangle-code/domain";
+import { compareCodepoints } from "@untangle-code/domain";
+import {
+  ACKNOWLEDGMENT_FILE_NAME,
+  acknowledgmentFilePath,
+  type ExtensionRunV1,
+  type LicenseAcknowledgmentFileV1,
+  type LicenseAcknowledgmentV1,
+} from "@untangle-code/extension-runtime";
+
+/** File name of the CLI's own state, next to the acknowledgment file. */
+export const CLI_STATE_FILE_NAME = "cli-state.json";
+
+/** Summary of one finished run — enough for `list`, not a substitute for it. */
+export interface LastRunRecordV1 {
+  runId: string;
+  startedAt: string;
+  finishedAt?: string;
+  exitStatus: ExtensionRunV1["exitStatus"];
+  findingsTotal: number;
+  errorCode?: string;
+}
+
+export interface CliStateV1 {
+  schemaVersion: 1;
+  /** Extension ids the user enabled (X1: enabling starts nothing). */
+  enabled: string[];
+  lastRuns: Record<string, LastRunRecordV1>;
+}
+
+export function summarizeRun(run: ExtensionRunV1): LastRunRecordV1 {
+  return {
+    runId: run.runId,
+    startedAt: run.startedAt,
+    ...(run.finishedAt === undefined ? {} : { finishedAt: run.finishedAt }),
+    exitStatus: run.exitStatus,
+    findingsTotal: run.findingsTotal,
+    ...(run.errorCode === undefined ? {} : { errorCode: run.errorCode }),
+  };
+}
+
+export function emptyCliState(): CliStateV1 {
+  return { schemaVersion: 1, enabled: [], lastRuns: {} };
+}
+
+export function cliStatePath(userDataDirectory: string): string {
+  return join(userDataDirectory, "extensions", CLI_STATE_FILE_NAME);
+}
+
+/** Result of reading a state file: the state plus anything unreadable (E4). */
+export interface LoadedCliStateV1 {
+  state: CliStateV1;
+  warnings: string[];
+}
+
+/**
+ * Reads the CLI state. A missing file means "nothing enabled, nothing run" —
+ * a valid starting state, not an error. A corrupt file is reported and
+ * treated as empty rather than crashing the command (X2).
+ */
+export async function loadCliState(
+  fs: FileSystemPort,
+  userDataDirectory: string,
+): Promise<LoadedCliStateV1> {
+  const path = cliStatePath(userDataDirectory);
+  let text: string;
+  try {
+    text = await fs.readTextFile(path);
+  } catch {
+    return { state: emptyCliState(), warnings: [] };
+  }
+  let document: unknown;
+  try {
+    document = JSON.parse(text) as unknown;
+  } catch (cause) {
+    return {
+      state: emptyCliState(),
+      warnings: [
+        `"${path}" is not valid JSON (${cause instanceof Error ? cause.message : String(cause)}); ` +
+          "enabled flags and last-run records are shown as unknown until the file is repaired",
+      ],
+    };
+  }
+  if (typeof document !== "object" || document === null || Array.isArray(document)) {
+    return { state: emptyCliState(), warnings: [`"${path}" is not a JSON object; ignored`] };
+  }
+  const record = document as Record<string, unknown>;
+  const enabled = Array.isArray(record["enabled"])
+    ? record["enabled"].filter((entry): entry is string => typeof entry === "string")
+    : [];
+  const lastRuns: Record<string, LastRunRecordV1> = {};
+  const rawRuns = record["lastRuns"];
+  if (typeof rawRuns === "object" && rawRuns !== null && !Array.isArray(rawRuns)) {
+    for (const [id, value] of Object.entries(rawRuns as Record<string, unknown>)) {
+      const parsed = readLastRun(value);
+      if (parsed !== null) {
+        lastRuns[id] = parsed;
+      }
+    }
+  }
+  return {
+    state: { schemaVersion: 1, enabled: [...enabled].sort(compareCodepoints), lastRuns },
+    warnings: [],
+  };
+}
+
+function readLastRun(value: unknown): LastRunRecordV1 | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const runId = record["runId"];
+  const startedAt = record["startedAt"];
+  const exitStatus = record["exitStatus"];
+  const findingsTotal = record["findingsTotal"];
+  if (
+    typeof runId !== "string" ||
+    typeof startedAt !== "string" ||
+    typeof exitStatus !== "string"
+  ) {
+    return null;
+  }
+  const finishedAt = record["finishedAt"];
+  const errorCode = record["errorCode"];
+  return {
+    runId,
+    startedAt,
+    exitStatus: exitStatus as ExtensionRunV1["exitStatus"],
+    findingsTotal: typeof findingsTotal === "number" ? findingsTotal : 0,
+    ...(typeof finishedAt === "string" ? { finishedAt } : {}),
+    ...(typeof errorCode === "string" ? { errorCode } : {}),
+  };
+}
+
+export async function saveCliState(
+  fs: FileSystemPort,
+  userDataDirectory: string,
+  state: CliStateV1,
+): Promise<string> {
+  const path = cliStatePath(userDataDirectory);
+  const ordered: CliStateV1 = {
+    schemaVersion: 1,
+    enabled: [...state.enabled].sort(compareCodepoints),
+    lastRuns: Object.fromEntries(
+      Object.entries(state.lastRuns).sort(([left], [right]) => compareCodepoints(left, right)),
+    ),
+  };
+  await writeJsonAtomic(fs, path, ordered);
+  return path;
+}
+
+/** Where acknowledgments are written; re-exported so callers need one import. */
+export function acknowledgmentPath(userDataDirectory: string): string {
+  return acknowledgmentFilePath(userDataDirectory);
+}
+
+export { ACKNOWLEDGMENT_FILE_NAME };
+
+/**
+ * Writes the acknowledgment file. Entries are ordered by
+ * `(extensionId, ruleset)` via codepoint comparison so the file has one
+ * canonical form — a diff between two machines shows real changes only.
+ */
+export async function saveAcknowledgments(
+  fs: FileSystemPort,
+  userDataDirectory: string,
+  acknowledgments: readonly LicenseAcknowledgmentV1[],
+): Promise<string> {
+  const path = acknowledgmentFilePath(userDataDirectory);
+  const document: LicenseAcknowledgmentFileV1 = {
+    schemaVersion: 1,
+    acknowledgments: [...acknowledgments].sort(
+      (left, right) =>
+        compareCodepoints(left.extensionId, right.extensionId) ||
+        compareCodepoints(left.ruleset ?? "", right.ruleset ?? ""),
+    ),
+  };
+  await writeJsonAtomic(fs, path, document);
+  return path;
+}
+
+/**
+ * Replaces the entry for one `(extensionId, ruleset)` pair, keeping the rest.
+ * A repeated acknowledgment updates in place instead of stacking duplicates.
+ */
+export function upsertAcknowledgment(
+  existing: readonly LicenseAcknowledgmentV1[],
+  entry: LicenseAcknowledgmentV1,
+): LicenseAcknowledgmentV1[] {
+  const kept = existing.filter(
+    (candidate) =>
+      candidate.extensionId !== entry.extensionId ||
+      (candidate.ruleset ?? "") !== (entry.ruleset ?? ""),
+  );
+  return [...kept, entry];
+}
+
+/**
+ * Marks every acknowledgment for one extension as withdrawn (§9.3).
+ *
+ * The entry is kept and stamped with `revokedAt` rather than deleted. Both
+ * shapes refuse the run, so this is not about safety — it is about what the
+ * user can be told afterwards. A deleted row makes "you never acknowledged
+ * this" and "you acknowledged this and took it back" indistinguishable, and
+ * §9.3 asks `status` to be able to show the gate status `revoked`, which a
+ * deleted row can never produce.
+ */
+export function revokeAcknowledgments(
+  existing: readonly LicenseAcknowledgmentV1[],
+  extensionId: string,
+  revokedAt: string,
+): LicenseAcknowledgmentV1[] {
+  return existing.map((candidate) =>
+    candidate.extensionId === extensionId && candidate.revokedAt === undefined
+      ? { ...candidate, revokedAt }
+      : candidate,
+  );
+}
+
+/** Drops every acknowledgment for one extension — used when it is uninstalled. */
+export function removeAcknowledgments(
+  existing: readonly LicenseAcknowledgmentV1[],
+  extensionId: string,
+): LicenseAcknowledgmentV1[] {
+  return existing.filter((candidate) => candidate.extensionId !== extensionId);
+}
+
+async function writeJsonAtomic(fs: FileSystemPort, path: string, value: unknown): Promise<void> {
+  await fs.mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp`;
+  const bytes = new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);
+  await fs.writeFile(temporary, bytes);
+  await fs.rename(temporary, path);
+}