@f5-sales-demo/xcsh 22.14.7 → 23.0.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ## Unreleased
 
+### Breaking changes
+
+- `request secrets encrypt` now emits bare base64; its policy retrieval requires `--name` and defaults to namespace `default`. Public documents default to camelCase YAML. The article consumer adds exactly one `string:///`. Canonical `blindfold` keeps snake_case JSON and location defaults.
+- Both paths accept known camelCase/snake_case aliases and explicit encryption encoding; compatibility `--outfile` writes raw envelopes securely, `--outfmt` selects public document format, and public-key retrieval supports exact unsigned key versions. No legacy authentication or runtime vesctl dependency is introduced.
+
+
 ### Added
 
 - Added shared host-aware software setup with live management probes, reviewed package-manager routes, checksum-verified per-user archives, and asynchronous CLI/TUI setup preparation ([#4598](https://github.com/f5-sales-demo/xcsh/issues/4598)).

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "22.14.7",
+	"version": "23.0.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -68,13 +68,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.4.0",
-		"@f5-sales-demo/pi-agent-core": "22.14.7",
-		"@f5-sales-demo/pi-ai": "22.14.7",
-		"@f5-sales-demo/pi-natives": "22.14.7",
-		"@f5-sales-demo/pi-resource-management": "22.14.7",
-		"@f5-sales-demo/pi-tui": "22.14.7",
-		"@f5-sales-demo/pi-utils": "22.14.7",
-		"@f5-sales-demo/xcsh-stats": "22.14.7",
+		"@f5-sales-demo/pi-agent-core": "23.0.0",
+		"@f5-sales-demo/pi-ai": "23.0.0",
+		"@f5-sales-demo/pi-natives": "23.0.0",
+		"@f5-sales-demo/pi-resource-management": "23.0.0",
+		"@f5-sales-demo/pi-tui": "23.0.0",
+		"@f5-sales-demo/pi-utils": "23.0.0",
+		"@f5-sales-demo/xcsh-stats": "23.0.0",
 		"@mozilla/readability": "^0.6",
 		"@resvg/resvg-wasm": "2.6.2",
 		"@sinclair/typebox": "0.34.52",

package/src/cli.ts

@@ -54,6 +54,7 @@ process.title = APP_NAME;
 
 const commands: CommandEntry[] = [
 	{ name: "context", load: () => import("./commands/context").then(m => m.default) },
+	{ name: "request", load: () => import("./commands/request").then(m => m.default) },
 	{ name: "blindfold", load: () => import("./commands/blindfold").then(m => m.default) },
 	{ name: "remote-control", load: () => import("./commands/remote-control").then(m => m.default) },
 	{ name: "apply", load: () => import("./commands/apply").then(m => m.default) },
@@ -125,6 +126,17 @@ function requestsHelp(args: readonly string[]): boolean {
 
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export function runCli(argv: string[]): Promise<void> {
+	if (["blindfold", "request"].includes(argv[0] ?? "")) {
+		if (requestsHelp(argv.slice(1)))
+			return import("./commands/blindfold-help").then(m => m.showBlindfoldHelp(argv, APP_NAME));
+		return import("./commands/blindfold")
+			.then(m => m.runBlindfold(argv.slice(1), argv[0] === "request"))
+			.catch(error => {
+				if (!(error instanceof CliUsageError)) throw error;
+				writeCliOutput(process.stderr, `Error: ${error.message}\n`);
+				process.exitCode = 2;
+			});
+	}
 	// --help and --version are handled by run() directly, don't rewrite those.
 	// Everything else that isn't a known subcommand routes to "launch".
 	// Keeping this routing boundary explicit makes the CLI fallback easy to audit.

package/src/commands/blindfold-args.ts

@@ -0,0 +1,141 @@
+import { resolve } from "node:path";
+import { Args, CliUsageError, Flags, parseCommandArgv } from "@f5-sales-demo/pi-utils/cli";
+import type { BlindfoldArgs, BlindfoldOperation } from "../services/blindfold";
+
+export const blindfoldFlags = {
+	input: Flags.string({ description: "Secret filename or - for stdin" }),
+	"public-key": Flags.string({ description: "Public key JSON/YAML file; requires --policy-document (offline)" }),
+	"policy-document": Flags.string({ description: "Policy JSON/YAML file; requires --public-key (offline)" }),
+	cert: Flags.string({ description: "PEM certificate chain" }),
+	key: Flags.string({ description: "PEM private key" }),
+	bundle: Flags.string({ description: "PKCS#12 bundle" }),
+	name: Flags.string({ description: "Certificate name or secret policy name" }),
+	namespace: Flags.string({ char: "n", description: "Certificate namespace or secret policy namespace" }),
+	policy: Flags.string({ description: "Secret policy namespace/name (default shared/ves-io-allow-volterra)" }),
+	"passphrase-env": Flags.string({ description: "Passphrase environment variable name" }),
+	"context-name": Flags.string({ description: "Assert selected native context (online only)" }),
+	encoding: Flags.string({ description: "Encryption text encoding", options: ["base64", "location"] }),
+	outfile: Flags.string({ description: "New raw binary envelope file (0600; compatibility only)" }),
+	outfmt: Flags.string({ description: "Compatibility public document format", options: ["json", "yaml"] }),
+	"key-version": Flags.string({ description: "Unsigned 32-bit public key version; zero selects server default" }),
+	output: Flags.string({ description: "Public material format", options: ["json", "yaml"] }),
+	"output-file": Flags.string({ description: "New artifact file (0600)" }),
+	"result-file": Flags.string({ description: "New public JSON report file (0600)" }),
+	"dry-run": Flags.string({ description: "Validate without tenant writes", options: ["client"] }),
+	json: Flags.boolean({ description: "Print public JSON report" }),
+};
+const aliases = { "get-public-key": "public-key", "get-policy-document": "policy", encrypt: "encrypt" } as const;
+const supported = ["public-key", "policy", "encrypt", "certificate", "create", "replace"];
+const common = ["context-name", "output-file", "result-file", "json"];
+export function flagsForBlindfold(operation: string, compatibility = false) {
+	const names =
+		operation === "public-key"
+			? [...common, "output", "key-version", ...(compatibility ? ["outfmt"] : [])]
+			: operation === "policy"
+				? [...common, "output", "namespace", "name", ...(compatibility ? ["outfmt"] : ["policy"])]
+				: operation === "encrypt"
+					? [
+							...common,
+							"input",
+							"policy",
+							"public-key",
+							"policy-document",
+							"encoding",
+							...(compatibility ? ["outfile", "outfmt"] : []),
+						]
+					: [...common, "cert", "key", "bundle", "name", "namespace", "policy", "passphrase-env", "dry-run"];
+	return Object.fromEntries(names.map(name => [name, blindfoldFlags[name as keyof typeof blindfoldFlags]]));
+}
+export function parseBlindfoldCli(
+	argv: readonly string[],
+	compatibility: boolean,
+	stdinIsTTY: boolean,
+): BlindfoldArgs & { json?: boolean } {
+	const parts = [...argv];
+	if (compatibility && parts.shift() !== "secrets") throw new CliUsageError("Only request secrets is supported");
+	const selected = parts.shift();
+	const operation = compatibility ? aliases[selected as keyof typeof aliases] : selected;
+	if (!operation || !supported.includes(operation)) throw new CliUsageError("Unknown Blindfold operation");
+	for (const arg of parts.slice(0, parts.includes("--") ? parts.indexOf("--") : undefined)) {
+		if (/^(--(?:config|server-urls|p12-bundle|cacert|cert|key|hw-key)(?:=|$)|-[acku])/.test(arg) && compatibility)
+			throw new CliUsageError("Legacy authentication is unsupported; configure xcsh context with xcsh context");
+	}
+	const parsed = parseCommandArgv(parts, {
+		flags: flagsForBlindfold(operation, compatibility),
+		args: operation === "encrypt" ? { file: Args.string() } : {},
+	});
+	if (parsed.argv.length > (operation === "encrypt" ? 1 : 0)) throw new CliUsageError("Surplus positional arguments");
+	const f = parsed.flags;
+	if (f.input !== undefined && parsed.args.file !== undefined)
+		throw new CliUsageError("Select one secret input source");
+	const args: BlindfoldArgs & { json?: boolean } = {
+		operation: operation as BlindfoldOperation,
+		compatibility,
+		encoding: f.encoding as "base64" | "location" | undefined,
+		outfile: f.outfile as string | undefined,
+		input: (f.input ?? parsed.args.file) as string | undefined,
+		publicKey: f["public-key"] as string | undefined,
+		policyDocument: f["policy-document"] as string | undefined,
+		cert: f.cert as string | undefined,
+		key: f.key as string | undefined,
+		bundle: f.bundle as string | undefined,
+		name: f.name as string | undefined,
+		namespace: f.namespace as string | undefined,
+		policy: f.policy as string | undefined,
+		passphraseEnv: f["passphrase-env"] as string | undefined,
+		contextName: f["context-name"] as string | undefined,
+		output: (f.output ?? (operation !== "encrypt" ? f.outfmt : undefined)) as "json" | "yaml" | undefined,
+		outputFile: f["output-file"] as string | undefined,
+		resultFile: f["result-file"] as string | undefined,
+		dryRun: f["dry-run"] as "client" | undefined,
+		json: f.json as boolean | undefined,
+	};
+	if (f.output !== undefined && f.outfmt !== undefined)
+		throw new CliUsageError("Conflicting public material format selectors");
+	if (f["key-version"] !== undefined) {
+		const version = String(f["key-version"]);
+		if (!/^[0-9]+$/.test(version) || !Number.isSafeInteger(Number(version)) || Number(version) > 0xffffffff)
+			throw new CliUsageError("Key version must be an unsigned 32-bit integer");
+		args.keyVersion = Number(version);
+	}
+	if (compatibility && operation === "policy") {
+		if (!args.name) throw new CliUsageError("Compatibility policy retrieval requires --name");
+		args.namespace ??= "default";
+	}
+	if (args.outfile && (args.outputFile || args.json || args.encoding))
+		throw new CliUsageError("Binary --outfile conflicts with textual encoding, --output-file or --json");
+	if (args.outfile && args.resultFile && resolve(args.outfile) === resolve(args.resultFile))
+		throw new CliUsageError("Artifact and report destinations must differ");
+	if (Boolean(args.publicKey) !== Boolean(args.policyDocument))
+		throw new CliUsageError("--public-key and --policy-document must be supplied together");
+	if (args.publicKey && args.contextName)
+		throw new CliUsageError("Offline encryption does not select a context; omit --context-name");
+	if (args.json && (args.outputFile || args.output)) throw new CliUsageError("Conflicting output selections");
+	if (operation === "policy" && args.policy && (args.namespace !== undefined || args.name !== undefined))
+		throw new CliUsageError("Cannot combine --policy with --namespace or --name");
+
+	const label = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+	if (args.policy && (args.policy.split("/").length !== 2 || args.policy.split("/").some(v => !label.test(v))))
+		throw new CliUsageError("Policy must be namespace/name");
+	if ([args.name, args.namespace].some(v => v !== undefined && !label.test(v)))
+		throw new CliUsageError("Invalid resource namespace or name");
+	if (
+		[args.input, args.publicKey, args.policyDocument, args.outputFile, args.outfile, args.resultFile].some(
+			v => v === "",
+		)
+	)
+		throw new CliUsageError("File paths must be nonempty");
+	if (["certificate", "create", "replace"].includes(operation)) {
+		if (!args.name || (args.bundle ? args.cert || args.key : !args.cert || !args.key))
+			throw new CliUsageError("Use --name and either --bundle or --cert with --key");
+	}
+	if (args.outputFile && args.resultFile && resolve(args.outputFile) === resolve(args.resultFile))
+		throw new CliUsageError("Artifact and report destinations must differ");
+	if (operation === "encrypt" && args.input === undefined) {
+		if (stdinIsTTY) throw new CliUsageError("Encrypt requires an input filename or redirected stdin");
+		args.input = "-";
+	}
+	if (operation === "encrypt" && args.input === "-" && stdinIsTTY)
+		throw new CliUsageError("Encrypt stdin must be redirected");
+	return args;
+}

package/src/commands/blindfold-help.ts

@@ -0,0 +1,51 @@
+import { type ArgDescriptor, Args, CliUsageError, Command, renderCommandHelp } from "@f5-sales-demo/pi-utils/cli";
+import { writeCliOutput } from "@f5-sales-demo/pi-utils/cli-output";
+import { flagsForBlindfold } from "./blindfold-args";
+export function showBlindfoldHelp(argv: string[], bin: string): void {
+	const compatibility = argv[0] === "request";
+	const leaf = compatibility ? argv[2] : argv[1];
+	const operation =
+		(
+			{ "get-public-key": "public-key", "get-policy-document": "policy", encrypt: "encrypt" } as Record<
+				string,
+				string
+			>
+		)[leaf ?? ""] ?? (!compatibility ? leaf : undefined);
+	if (compatibility && argv[1] && !["secrets", "-h", "--help"].includes(argv[1])) {
+		writeCliOutput(process.stderr, "Error: Only request secrets is supported\n");
+		process.exitCode = 2;
+		return;
+	}
+	if (!operation || ["--help", "-h"].includes(operation)) {
+		writeCliOutput(
+			process.stdout,
+			`${bin} ${compatibility ? "request secrets" : "blindfold"} ${compatibility ? "get-public-key | get-policy-document | encrypt" : "public-key | policy | encrypt | certificate | create | replace"}\nUse an operation followed by --help. Authentication uses xcsh context.\n`,
+		);
+		return;
+	}
+	try {
+		if (
+			!["public-key", "policy", "encrypt", "certificate", "create", "replace"].includes(operation) ||
+			(compatibility && !["get-public-key", "get-policy-document", "encrypt"].includes(leaf!))
+		)
+			throw new CliUsageError("Unknown Blindfold operation");
+		class Help extends Command {
+			static description =
+				operation === "encrypt"
+					? "Encrypt an input file or redirected stdin; paired public material files select offline operation"
+					: operation === "policy"
+						? "Retrieve a secret policy document; namespace/name select the policy"
+						: "Native Blindfold operation";
+			static flags = flagsForBlindfold(operation!, compatibility);
+			static args: Record<string, ArgDescriptor> =
+				operation === "encrypt"
+					? { file: Args.string({ description: "Filename or -; omit for redirected stdin" }) }
+					: {};
+			async run() {}
+		}
+		renderCommandHelp(bin, argv.slice(0, compatibility ? 3 : 2).join(" "), Help);
+	} catch (error) {
+		writeCliOutput(process.stderr, `Error: ${error instanceof Error ? error.message : "invalid operation"}\n`);
+		process.exitCode = 2;
+	}
+}

package/src/commands/blindfold.ts

@@ -1,80 +1,55 @@
-import { Args, Command, Flags } from "@f5-sales-demo/pi-utils/cli";
-import { Settings } from "../config/settings";
-import { BLINDFOLD_OPERATIONS, type BlindfoldOperation, BlindfoldService } from "../services/blindfold";
-import { ContextService } from "../services/xcsh-context";
+import { Args, Command } from "@f5-sales-demo/pi-utils/cli";
+import { writeCliOutput } from "@f5-sales-demo/pi-utils/cli-output";
 
+import { BlindfoldService } from "../services/blindfold";
+import type { ContextService } from "../services/xcsh-context";
+import { blindfoldFlags, parseBlindfoldCli } from "./blindfold-args";
+export async function runBlindfold(argv: string[], compatibility = false): Promise<void> {
+	const args = parseBlindfoldCli(argv, compatibility, Boolean(process.stdin.isTTY));
+	let context: ContextService | undefined;
+	const controller = new AbortController();
+	const cancel = () => controller.abort();
+	process.once("SIGINT", cancel);
+	try {
+		let env: Record<string, string | undefined> = {};
+		if (!args.publicKey) {
+			const { Settings } = await import("../config/settings");
+			const { ContextService } = await import("../services/xcsh-context");
+			await Settings.init({ cwd: process.cwd() });
+			context = await ContextService.getOrInit(undefined, process.cwd());
+			env = { ...(Settings.instance.get("bash.environment") as Record<string, string> | undefined), ...process.env };
+		}
+		const service = new BlindfoldService({
+			env,
+			emit: content => {
+				if (!args.json && !args.outputFile) writeCliOutput(process.stdout, content);
+			},
+		});
+		const report = await service.run(args, { signal: controller.signal });
+		if (args.json || args.outputFile || ["create", "replace"].includes(report.operation))
+			writeCliOutput(process.stdout, `${JSON.stringify(report, null, 2)}\n`);
+	} catch (error) {
+		writeCliOutput(
+			process.stderr,
+			`Blindfold: ${controller.signal.aborted ? "operation cancelled" : error instanceof Error ? error.message : "operation failed"}\n`,
+		);
+		process.exitCode = controller.signal.aborted ? 130 : 1;
+	} finally {
+		context?.stopRevalidation();
+		process.removeListener("SIGINT", cancel);
+	}
+}
 export default class Blindfold extends Command {
 	static description = "Encrypt secrets natively and create or rotate tenant TLS certificates";
 	static args = {
 		operation: Args.string({
 			required: true,
-			options: [...BLINDFOLD_OPERATIONS],
-			description: "public-key, policy, encrypt, certificate, create, or replace",
+			description: "public-key, policy, encrypt, certificate, create, replace",
 		}),
+		file: Args.string({ description: "Encryption input file or - for redirected stdin" }),
 	};
-	static flags = {
-		input: Flags.string({ description: "Secret file to encrypt" }),
-		cert: Flags.string({ description: "PEM certificate chain" }),
-		key: Flags.string({ description: "PEM private key" }),
-		bundle: Flags.string({ description: "PKCS#12 .p12/.pfx bundle" }),
-		name: Flags.string({ description: "Certificate resource name" }),
-		namespace: Flags.string({ char: "n", description: "Certificate namespace; defaults to XCSH_NAMESPACE" }),
-		policy: Flags.string({ description: "Secret policy namespace/name", default: "shared/ves-io-allow-volterra" }),
-		"passphrase-env": Flags.string({
-			description: "Name of an environment variable containing the input passphrase",
-		}),
-		"context-name": Flags.string({ description: "Expected active context; fail if different" }),
-		"output-file": Flags.string({ description: "Create a new encrypted artifact or public material file (0600)" }),
-		"result-file": Flags.string({ description: "Create a new JSON report (0600)" }),
-		"dry-run": Flags.string({ description: "Validate without tenant writes", options: ["client"] }),
-		json: Flags.boolean({ description: "Print the public JSON report" }),
-	};
+	static flags = blindfoldFlags;
 	async run(): Promise<void> {
-		const { args, flags } = await this.parse(Blindfold);
-		let context: ContextService | undefined;
-		const controller = new AbortController();
-		const cancel = () => controller.abort();
-		process.once("SIGINT", cancel);
-		try {
-			await Settings.init({ cwd: process.cwd() });
-			context = await ContextService.getOrInit(undefined, process.cwd());
-			const env = {
-				...(Settings.instance.get("bash.environment") as Record<string, string> | undefined),
-				...process.env,
-			};
-			const service = new BlindfoldService({
-				env,
-				emit: content => {
-					if (!flags.json && !flags["output-file"]) process.stdout.write(content);
-				},
-			});
-			const report = await service.run(
-				{
-					operation: args.operation as BlindfoldOperation,
-					input: flags.input,
-					cert: flags.cert,
-					key: flags.key,
-					bundle: flags.bundle,
-					name: flags.name,
-					namespace: flags.namespace,
-					policy: flags.policy,
-					passphraseEnv: flags["passphrase-env"],
-					contextName: flags["context-name"],
-					outputFile: flags["output-file"],
-					resultFile: flags["result-file"],
-					dryRun: flags["dry-run"] as "client" | undefined,
-				},
-				{ signal: controller.signal },
-			);
-			if (flags.json || flags["output-file"] || ["create", "replace"].includes(report.operation))
-				process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-			context.stopRevalidation();
-		} catch (error) {
-			process.stderr.write(`Blindfold: ${error instanceof Error ? error.message : "operation failed"}\n`);
-			process.exitCode = 1;
-		} finally {
-			context?.stopRevalidation();
-			process.removeListener("SIGINT", cancel);
-		}
+		await runBlindfold(this.argv);
 	}
 }

package/src/commands/request.ts

@@ -0,0 +1,12 @@
+import { Args, Command } from "@f5-sales-demo/pi-utils/cli";
+import { runBlindfold } from "./blindfold";
+export default class Request extends Command {
+	static description = "Native compatibility for request secrets get-public-key, get-policy-document, encrypt";
+	static args = {
+		secrets: Args.string({ required: true, options: ["secrets"] }),
+		operation: Args.string({ required: true, options: ["get-public-key", "get-policy-document", "encrypt"] }),
+	};
+	async run(): Promise<void> {
+		await runBlindfold(this.argv, true);
+	}
+}