@untangle-code/cli 0.0.0-stage → 0.1.0

package/dist/commands/extensions/secret-store.d.ts

@@ -0,0 +1,15 @@
+import type { ExtensionManifestV1 } from "@untangle-code/domain";
+import { type ExtensionEnvironmentV1 } from "./environment.js";
+export declare function secretStorePath(environment: ExtensionEnvironmentV1, id: string): string;
+export declare function credentialEndpoint(url?: string): string | null;
+/** Error messages intentionally contain neither raw JSON nor credential values. */
+export declare function parseSecretValues(value: unknown, manifest: ExtensionManifestV1): Record<string, string>;
+export declare function hasCode(error: unknown, code: string): boolean;
+export declare function readStoredSecrets(environment: ExtensionEnvironmentV1, manifest: ExtensionManifestV1, url?: string | undefined): Promise<Record<string, string>>;
+export declare function secretEnvironment(environment: ExtensionEnvironmentV1, manifest: ExtensionManifestV1, stored: Readonly<Record<string, string>>): Record<string, string | undefined>;
+/** A complete environment override does not depend on an old endpoint's config. */
+export declare function resolveSecretEnvironment(environment: ExtensionEnvironmentV1, manifest: ExtensionManifestV1, url?: string | undefined): Promise<Record<string, string | undefined>>;
+/** Caller holds the per-extension lock while changing stored credentials. */
+export declare function writeStoredSecrets(environment: ExtensionEnvironmentV1, manifest: ExtensionManifestV1, values: Readonly<Record<string, string>>, url?: string | undefined): Promise<void>;
+export declare function withSecretLock<T>(environment: ExtensionEnvironmentV1, id: string, action: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=secret-store.d.ts.map

package/dist/commands/extensions/secret-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-store.d.ts","sourceRoot":"","sources":["../../../src/commands/extensions/secret-store.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAAiC,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE9F,wBAAgB,eAAe,CAAC,WAAW,EAAE,sBAAsB,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAe9D;AAMD,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,mBAAmB,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AA+BD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,sBAAsB,EACnC,QAAQ,EAAE,mBAAmB,EAC7B,GAAG,qBAA4B,GAC9B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuCjC;AAED,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,sBAAsB,EACnC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAMpC;AAED,mFAAmF;AACnF,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,sBAAsB,EACnC,QAAQ,EAAE,mBAAmB,EAC7B,GAAG,qBAA4B,GAC9B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAS7C;AAED,6EAA6E;AAC7E,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,sBAAsB,EACnC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACxC,GAAG,qBAA4B,GAC9B,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED,wBAAsB,cAAc,CAAC,CAAC,EACpC,WAAW,EAAE,sBAAsB,EACnC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAmBZ"}

package/dist/commands/extensions/secret-store.js

@@ -0,0 +1,164 @@
+/** Private, endpoint-bound extension credentials; never part of project configuration. */
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { canonicalize, isInsideAnyRoot } from "./environment.js";
+export function secretStorePath(environment, id) {
+    return join(environment.userDataDir, "extension-secrets", `${id}.json`);
+}
+export function credentialEndpoint(url) {
+    if (url === undefined)
+        return null;
+    const parsed = new URL(url);
+    if (!["http:", "https:"].includes(parsed.protocol) ||
+        parsed.username ||
+        parsed.password ||
+        parsed.search ||
+        parsed.hash) {
+        throw new Error("Credential endpoint must be an HTTP(S) base URL without credentials, query or fragment.");
+    }
+    return parsed.href.replace(/\/$/u, "");
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Error messages intentionally contain neither raw JSON nor credential values. */
+export function parseSecretValues(value, manifest) {
+    if (!isRecord(value))
+        throw new Error("Credential configuration must be an object keyed by declared secret names.");
+    const declared = new Set(manifest.secrets.map((secret) => secret.name));
+    const entries = Object.entries(value);
+    if (entries.some(([name, secret]) => !declared.has(name) || typeof secret !== "string" || secret.includes("\0"))) {
+        throw new Error("Credential configuration contains an undeclared secret or a non-string value.");
+    }
+    return Object.fromEntries(entries);
+}
+async function checkDirectory(environment, create) {
+    const directory = dirname(secretStorePath(environment, "placeholder"));
+    const canonical = await canonicalize(environment.fs, directory);
+    if (isInsideAnyRoot(canonical, environment.projectRoots)) {
+        throw new Error("Extension credentials must be stored outside project directories.");
+    }
+    if (create)
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+    try {
+        const info = await lstat(directory);
+        if (!info.isDirectory() ||
+            info.isSymbolicLink() ||
+            (process.platform !== "win32" &&
+                ((info.mode & 0o077) !== 0 || info.uid !== process.getuid?.()))) {
+            throw new Error(`Credential directory must be owned by this user with mode 0700: ${directory}`);
+        }
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT") && !create)
+            return directory;
+        throw error;
+    }
+    return directory;
+}
+export function hasCode(error, code) {
+    return isRecord(error) && error["code"] === code;
+}
+export async function readStoredSecrets(environment, manifest, url = manifest.http?.defaultUrl) {
+    if (manifest.secrets.length === 0)
+        return {};
+    await checkDirectory(environment, false);
+    const path = secretStorePath(environment, manifest.id);
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return {};
+        throw new Error(`Cannot safely open credential configuration: ${path}`);
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() ||
+            info.size > 1_048_576 ||
+            (process.platform !== "win32" &&
+                ((info.mode & 0o077) !== 0 || info.uid !== process.getuid?.()))) {
+            throw new Error(`Credential configuration must be a user-owned file with mode 0600: ${path}`);
+        }
+        let value;
+        try {
+            value = JSON.parse(await handle.readFile("utf8"));
+        }
+        catch {
+            throw new Error(`Invalid JSON in credential configuration: ${path}`);
+        }
+        if (!isRecord(value) || value["schemaVersion"] !== 1 || value["extensionId"] !== manifest.id) {
+            throw new Error(`Invalid credential configuration schema: ${path}`);
+        }
+        if (value["endpoint"] !== credentialEndpoint(url)) {
+            throw new Error("Stored credentials belong to a different endpoint; configure credentials for the selected endpoint first.");
+        }
+        return parseSecretValues(value["secrets"], manifest);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function secretEnvironment(environment, manifest, stored) {
+    const env = { ...environment.env };
+    for (const secret of manifest.secrets) {
+        if (!env[secret.envVar] && stored[secret.name])
+            env[secret.envVar] = stored[secret.name];
+    }
+    return env;
+}
+/** A complete environment override does not depend on an old endpoint's config. */
+export async function resolveSecretEnvironment(environment, manifest, url = manifest.http?.defaultUrl) {
+    const needsStoredValues = manifest.secrets.some((secret) => !secret.setupOnly && !environment.env[secret.envVar]);
+    return secretEnvironment(environment, manifest, needsStoredValues ? await readStoredSecrets(environment, manifest, url) : {});
+}
+/** Caller holds the per-extension lock while changing stored credentials. */
+export async function writeStoredSecrets(environment, manifest, values, url = manifest.http?.defaultUrl) {
+    await checkDirectory(environment, true);
+    const secrets = parseSecretValues(values, manifest);
+    const path = secretStorePath(environment, manifest.id);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(JSON.stringify({
+                schemaVersion: 1,
+                extensionId: manifest.id,
+                endpoint: credentialEndpoint(url),
+                secrets,
+            }, null, 2) + "\n");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function withSecretLock(environment, id, action) {
+    const directory = await checkDirectory(environment, true);
+    const path = join(directory, `${id}.lock`);
+    let handle;
+    try {
+        handle = await open(path, "wx", 0o600);
+    }
+    catch (error) {
+        if (hasCode(error, "EEXIST"))
+            throw new Error(`Credential setup is already locked for ${id}; retry after it finishes. If interrupted, inspect and remove ${path}.`);
+        throw new Error("Cannot lock the private credential store.");
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await handle.close();
+        await rm(path, { force: true });
+    }
+}
+//# sourceMappingURL=secret-store.js.map

package/dist/commands/extensions/secret-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-store.js","sourceRoot":"","sources":["../../../src/commands/extensions/secret-store.ts"],"names":[],"mappings":"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"}

package/dist/commands/extensions/setup.d.ts

@@ -0,0 +1,17 @@
+/** Runs a user-supplied setup provider after consent, ownership and digest checks. */
+import type { ExtensionManifestV1 } from "@untangle-code/domain";
+import { type ProcessLimitsV1, type ProcessRunnerPort } from "@untangle-code/extension-runtime";
+import type { ExtensionEnvironmentV1 } from "./environment.js";
+import { type ProvisionResultV1 } from "./provision.js";
+export declare function missingAnalyzerSecrets(manifest: ExtensionManifestV1, env: Readonly<Record<string, string | undefined>>): string[];
+export declare function setupCredentials(input: {
+    environment: ExtensionEnvironmentV1;
+    manifest: ExtensionManifestV1;
+    provision?: ProvisionResultV1;
+    consent: boolean;
+    url?: string;
+    processRunner: ProcessRunnerPort;
+    limits: ProcessLimitsV1;
+    signal?: AbortSignal;
+}): Promise<Record<string, string | undefined>>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/commands/extensions/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/commands/extensions/setup.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAUzE,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,mBAAmB,EAC7B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAChD,MAAM,EAAE,CASV;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE;IAC5C,WAAW,EAAE,sBAAsB,CAAC;IACpC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,iBAAiB,CAAC;IACjC,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAiG9C"}

package/dist/commands/extensions/setup.js

@@ -0,0 +1,94 @@
+import { isLoopbackUrl, } from "@untangle-code/extension-runtime";
+import { primaryHostPort } from "./provision.js";
+import { credentialEndpoint, parseSecretValues, readStoredSecrets, secretEnvironment, withSecretLock, writeStoredSecrets, } from "./secret-store.js";
+export function missingAnalyzerSecrets(manifest, env) {
+    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) {
+    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 = {
+            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;
+        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;
+    });
+}
+//# sourceMappingURL=setup.js.map

package/dist/commands/extensions/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/commands/extensions/setup.ts"],"names":[],"mappings":"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"}

package/dist/commands/extensions/source.d.ts

@@ -0,0 +1,47 @@
+import type { FileSystemPort } from "@untangle-code/domain";
+/** Largest manifest this CLI will accept from a URL. */
+export declare const MAX_MANIFEST_BYTES: number;
+/** Network read budget for one manifest fetch. */
+export declare const FETCH_TIMEOUT_MS = 30000;
+export declare const DIGEST_PATTERN: RegExp;
+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 declare class ManifestSourceError extends Error {
+    constructor(message: string);
+}
+/** True when the argument looks like a URL rather than a path. */
+export declare function isUrlSource(from: string): boolean;
+export declare function digestOf(bytes: Uint8Array): string;
+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 declare function readManifestFromPath(fs: FileSystemPort, path: string): Promise<ManifestSourceV1>;
+/**
+ * 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 declare function fetchManifestFromUrl(url: string, options?: FetchManifestOptions): Promise<ManifestSourceV1>;
+//# sourceMappingURL=source.d.ts.map

package/dist/commands/extensions/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/commands/extensions/source.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,QAAa,CAAC;AAE7C,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,eAAO,MAAM,cAAc,QAA0B,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAInC;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAElD;AAED,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAsB3B;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAkE3B"}

package/dist/commands/extensions/source.js

@@ -0,0 +1,142 @@
+/**
+ * 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 { 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 class ManifestSourceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ManifestSourceError";
+    }
+}
+/** True when the argument looks like a URL rather than a path. */
+export function isUrlSource(from) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(from);
+}
+export function digestOf(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/**
+ * 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, path) {
+    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;
+    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, options = {}) {
+    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) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=source.js.map

package/dist/commands/extensions/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../../src/commands/extensions/source.ts"],"names":[],"mappings":"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"}

package/dist/commands/extensions/state.d.ts

@@ -0,0 +1,62 @@
+import type { FileSystemPort } from "@untangle-code/domain";
+import { ACKNOWLEDGMENT_FILE_NAME, type ExtensionRunV1, type LicenseAcknowledgmentV1 } from "@untangle-code/extension-runtime";
+/** File name of the CLI's own state, next to the acknowledgment file. */
+export declare 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 declare function summarizeRun(run: ExtensionRunV1): LastRunRecordV1;
+export declare function emptyCliState(): CliStateV1;
+export declare function cliStatePath(userDataDirectory: string): string;
+/** 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 declare function loadCliState(fs: FileSystemPort, userDataDirectory: string): Promise<LoadedCliStateV1>;
+export declare function saveCliState(fs: FileSystemPort, userDataDirectory: string, state: CliStateV1): Promise<string>;
+/** Where acknowledgments are written; re-exported so callers need one import. */
+export declare function acknowledgmentPath(userDataDirectory: string): string;
+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 declare function saveAcknowledgments(fs: FileSystemPort, userDataDirectory: string, acknowledgments: readonly LicenseAcknowledgmentV1[]): Promise<string>;
+/**
+ * Replaces the entry for one `(extensionId, ruleset)` pair, keeping the rest.
+ * A repeated acknowledgment updates in place instead of stacking duplicates.
+ */
+export declare function upsertAcknowledgment(existing: readonly LicenseAcknowledgmentV1[], entry: LicenseAcknowledgmentV1): LicenseAcknowledgmentV1[];
+/**
+ * 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 declare function revokeAcknowledgments(existing: readonly LicenseAcknowledgmentV1[], extensionId: string, revokedAt: string): LicenseAcknowledgmentV1[];
+/** Drops every acknowledgment for one extension — used when it is uninstalled. */
+export declare function removeAcknowledgments(existing: readonly LicenseAcknowledgmentV1[], extensionId: string): LicenseAcknowledgmentV1[];
+//# sourceMappingURL=state.d.ts.map

package/dist/commands/extensions/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/commands/extensions/state.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EACL,wBAAwB,EAExB,KAAK,cAAc,EAEnB,KAAK,uBAAuB,EAC7B,MAAM,kCAAkC,CAAC;AAE1C,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,CAAC;IACjB,oEAAoE;IACpE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC3C;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,eAAe,CASjE;AAED,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED,wBAAgB,YAAY,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,cAAc,EAClB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAyC3B;AA8BD,wBAAsB,YAAY,CAChC,EAAE,EAAE,cAAc,EAClB,iBAAiB,EAAE,MAAM,EACzB,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAEpC;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,cAAc,EAClB,iBAAiB,EAAE,MAAM,EACzB,eAAe,EAAE,SAAS,uBAAuB,EAAE,GAClD,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,KAAK,EAAE,uBAAuB,GAC7B,uBAAuB,EAAE,CAO3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,uBAAuB,EAAE,CAM3B;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,WAAW,EAAE,MAAM,GAClB,uBAAuB,EAAE,CAE3B"}