@smonn/ids 0.9.0 → 0.9.2

package/dist/cli.mjs

@@ -1,10 +1,44 @@
 #!/usr/bin/env node
 import { n as isIdsError } from "./error-Cp5qYZcv.mjs";
-import { t as createTimestampId } from "./timestamp-BjIMQkJf.mjs";
-import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-BQOlZ2oD.mjs";
-import { t as createReverseTimestampId } from "./reverse-C12D1btB.mjs";
-import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-CwqKTFaQ.mjs";
-import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-DKOsN_dq.mjs";
+import { t as createTimestampId } from "./timestamp-BbZL8hwg.mjs";
+import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-BpqxV8oB.mjs";
+import { t as createReverseTimestampId } from "./reverse-d5uEoIET.mjs";
+import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-BnRSC03a.mjs";
+import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-BI9UXnAm.mjs";
+//#region src/cli/key-io.ts
+function isKeyFormatError(result) {
+	return result !== "hex" && result !== "base64url";
+}
+function parseKeyFormatFlag(values) {
+	const fromFlag = values.get("--key-format");
+	if (fromFlag === void 0) return void 0;
+	if (fromFlag === "") return "--key-format requires a value";
+	if (fromFlag === "hex" || fromFlag === "base64url") return fromFlag;
+	return `--key-format must be hex or base64url, got '${fromFlag}'`;
+}
+function parseKeyFormatFromFlag(values) {
+	const fromFlag = parseKeyFormatFlag(values);
+	if (fromFlag === void 0) return "hex";
+	return fromFlag;
+}
+function parseKeyFormat(values, opts, facet) {
+	const fromFlag = parseKeyFormatFlag(values);
+	if (fromFlag !== void 0) return fromFlag;
+	const fromEnv = (opts.env ?? process.env)[facet.formatEnvVar];
+	if (fromEnv === void 0 || fromEnv === "") return "hex";
+	if (fromEnv === "hex" || fromEnv === "base64url") return fromEnv;
+	return `${facet.formatEnvVar} must be hex or base64url, got '${fromEnv}'`;
+}
+async function loadKey(opts, format, facet) {
+	const raw = (opts.env ?? process.env)[facet.envVar];
+	if (raw === void 0 || raw === "") return `missing ${facet.envVar} environment variable`;
+	try {
+		return await facet.import(facet.decode(raw, format));
+	} catch (err) {
+		return err.message;
+	}
+}
+//#endregion
 //#region src/cli/codec-options.ts
 function codecOpts(opts) {
 	const o = { allowDuplicateBrand: true };
@@ -13,73 +47,6 @@ function codecOpts(opts) {
 	return o;
 }
 //#endregion
-//#region src/cli/format.ts
-function formatCliError(err) {
-	return isIdsError(err) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
-}
-function formatWrappedInspectOutput(result) {
-	const inputLine = describeInputForm(result.input, result.canonical);
-	return [
-		`brand:      ${result.brand}`,
-		`lookup-key: ${result.lookupKey.toString()}`,
-		`canonical:  ${result.canonical}`,
-		`input:      ${inputLine}`,
-		""
-	].join("\n");
-}
-function formatSignedInspectOutput(result) {
-	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
-	const inputLine = describeInputForm(result.input, result.canonical);
-	const lines = [`brand:     ${result.brand}`, `timestamp: ${result.timestamp.toISOString()} (${relative})`];
-	if (result.verification !== void 0) lines.push(`verification: ${result.verification}`);
-	lines.push(`canonical: ${result.canonical}`, `input:     ${inputLine}`, "");
-	return lines.join("\n");
-}
-function formatInspectOutput(result) {
-	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
-	const inputLine = describeInputForm(result.input, result.canonical);
-	return [
-		`brand:     ${result.brand}`,
-		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
-		`canonical: ${result.canonical}`,
-		`input:     ${inputLine}`,
-		""
-	].join("\n");
-}
-function describeInputForm(input, canonical) {
-	if (input === canonical) return "canonical";
-	const notes = [];
-	if (input !== input.toLowerCase()) notes.push("was uppercase");
-	if (/[ilo]/i.test(input.slice(4))) notes.push("used Crockford aliases");
-	return `not canonical (${notes.join(" + ")})`;
-}
-const msPerMinute = 60 * 1e3;
-const msPerHour = 60 * msPerMinute;
-const msPerDay = 24 * msPerHour;
-const daysPerMonth = 30.44;
-const monthsPerYear = 12;
-function formatRelative(thenMs, nowMs) {
-	const diff = nowMs - thenMs;
-	const abs = Math.abs(diff);
-	const suffix = diff < 0 ? "from now" : "ago";
-	const head = headUnits(abs);
-	return head === "" ? "just now" : `${head} ${suffix}`;
-}
-function headUnits(abs) {
-	if (abs < msPerMinute) return "";
-	if (abs < msPerHour) return unit(Math.round(abs / msPerMinute), "minute");
-	if (abs < msPerDay) return unit(Math.round(abs / msPerHour), "hour");
-	if (abs < msPerDay * daysPerMonth) return unit(Math.round(abs / msPerDay), "day");
-	const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));
-	if (totalMonths < monthsPerYear) return unit(totalMonths, "month");
-	const years = Math.floor(totalMonths / monthsPerYear);
-	const months = totalMonths % monthsPerYear;
-	return months === 0 ? unit(years, "year") : `${unit(years, "year")} ${unit(months, "month")}`;
-}
-function unit(n, name) {
-	return `${n} ${n === 1 ? name : `${name}s`}`;
-}
-//#endregion
 //#region src/cli/constants.ts
 const maxGenerateCount = 1e4;
 //#endregion
@@ -95,19 +62,12 @@ function splitFlagToken(arg) {
 		inlineValue: arg.slice(eq + 1)
 	};
 }
-function splitFlags(args) {
+function splitFlags(args, valueFlags) {
 	const flags = /* @__PURE__ */ new Set();
 	const values = /* @__PURE__ */ new Map();
 	const positionals = [];
 	const errors = [];
 	const seenFlags = /* @__PURE__ */ new Set();
-	const valueFlags = new Set([
-		"--count",
-		"-c",
-		"--bits",
-		"--key-format",
-		"--kind"
-	]);
 	const addFlag = (flag) => {
 		const canonical = canonicalFlag(flag);
 		if (seenFlags.has(canonical)) errors.push(`duplicate flag: ${canonical}`);
@@ -117,11 +77,6 @@ function splitFlags(args) {
 	for (let i = 0; i < args.length; i++) {
 		const raw = args[i];
 		const { flag, inlineValue } = splitFlagToken(raw);
-		if (flag === "--opaque" || flag === "--wrapped" || flag === "--reverse" || flag === "--signed") {
-			addFlag(flag);
-			if (inlineValue !== void 0) errors.push(`flag does not take a value: ${flag}`);
-			continue;
-		}
 		if (valueFlags.has(flag)) {
 			if (inlineValue !== void 0) {
 				addFlag(flag);
@@ -141,6 +96,7 @@ function splitFlags(args) {
 		}
 		if (flag.startsWith("-")) {
 			addFlag(flag);
+			if (inlineValue !== void 0) errors.push(`flag does not take a value: ${flag}`);
 			continue;
 		}
 		positionals.push(raw);
@@ -156,7 +112,7 @@ function canonicalFlag(flag) {
 	if (flag === "-c") return "--count";
 	return flag;
 }
-const knownFlags = new Set([
+const knownFlags = /* @__PURE__ */ new Set([
 	"--opaque",
 	"--wrapped",
 	"--reverse",
@@ -199,211 +155,267 @@ function isKindError(result) {
 	return result !== "u32" && result !== "i32" && result !== "u64" && result !== "i64";
 }
 //#endregion
-//#region src/cli/key-io.ts
-function isKeyFormatError(result) {
-	return result !== "hex" && result !== "base64url";
+//#region src/cli/format.ts
+function formatCliError(err) {
+	return isIdsError(err) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
 }
-function parseKeyFormatFlag(values) {
-	const fromFlag = values.get("--key-format");
-	if (fromFlag === void 0) return void 0;
-	if (fromFlag === "") return "--key-format requires a value";
-	if (fromFlag === "hex" || fromFlag === "base64url") return fromFlag;
-	return `--key-format must be hex or base64url, got '${fromFlag}'`;
+function formatWrappedInspectOutput(result) {
+	const inputLine = describeInputForm(result.input, result.canonical);
+	return [
+		`brand:      ${result.brand}`,
+		`lookup-key: ${result.lookupKey.toString()}`,
+		`canonical:  ${result.canonical}`,
+		`input:      ${inputLine}`,
+		""
+	].join("\n");
 }
-function parseKeyFormatFromFlag(values) {
-	const fromFlag = parseKeyFormatFlag(values);
-	if (fromFlag === void 0) return "hex";
-	return fromFlag;
+function formatSignedInspectOutput(result) {
+	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
+	const inputLine = describeInputForm(result.input, result.canonical);
+	const lines = [`brand:     ${result.brand}`, `timestamp: ${result.timestamp.toISOString()} (${relative})`];
+	lines.push(`verification: ${result.verification}`);
+	lines.push(`canonical: ${result.canonical}`, `input:     ${inputLine}`, "");
+	return lines.join("\n");
 }
-function parseKeyFormat(values, opts, facet) {
-	const fromFlag = parseKeyFormatFlag(values);
-	if (fromFlag !== void 0) return fromFlag;
-	const fromEnv = (opts.env ?? process.env)[facet.formatEnvVar];
-	if (fromEnv === void 0 || fromEnv === "") return "hex";
-	if (fromEnv === "hex" || fromEnv === "base64url") return fromEnv;
-	return `${facet.formatEnvVar} must be hex or base64url, got '${fromEnv}'`;
+function formatInspectOutput(result) {
+	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
+	const inputLine = describeInputForm(result.input, result.canonical);
+	return [
+		`brand:     ${result.brand}`,
+		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
+		`canonical: ${result.canonical}`,
+		`input:     ${inputLine}`,
+		""
+	].join("\n");
 }
-async function loadKey(opts, format, facet) {
-	const raw = (opts.env ?? process.env)[facet.envVar];
-	if (raw === void 0 || raw === "") return `missing ${facet.envVar} environment variable`;
-	try {
-		return await facet.import(facet.decode(raw, format));
-	} catch (err) {
-		return err.message;
-	}
+function describeInputForm(input, canonical) {
+	if (input === canonical) return "canonical";
+	const notes = [];
+	if (input !== input.toLowerCase()) notes.push("was uppercase");
+	if (/[ilo]/i.test(input.slice(4))) notes.push("used Crockford aliases");
+	return `not canonical (${notes.join(" + ")})`;
 }
-//#endregion
-//#region src/cli/opaque-key.ts
-const opaqueFacet = {
-	envVar: "IDS_KEY",
-	formatEnvVar: "IDS_KEY_FORMAT",
-	decode: decodeOpaqueKey,
-	import: importOpaqueKey
-};
-function parseKeygenFormat(values) {
-	return parseKeyFormatFromFlag(values);
+const msPerMinute = 60 * 1e3;
+const msPerHour = 60 * msPerMinute;
+const msPerDay = 24 * msPerHour;
+const daysPerMonth = 30.44;
+const monthsPerYear = 12;
+function formatRelative(thenMs, nowMs) {
+	const diff = nowMs - thenMs;
+	const abs = Math.abs(diff);
+	const suffix = diff < 0 ? "from now" : "ago";
+	const head = headUnits(abs);
+	return head === "" ? "just now" : `${head} ${suffix}`;
 }
-function parseOpaqueKeyFormat(values, opts) {
-	return parseKeyFormat(values, opts, opaqueFacet);
+function headUnits(abs) {
+	if (abs < msPerMinute) return "";
+	if (abs < msPerHour) return unit(Math.round(abs / msPerMinute), "minute");
+	if (abs < msPerDay) return unit(Math.round(abs / msPerHour), "hour");
+	if (abs < msPerDay * daysPerMonth) return unit(Math.round(abs / msPerDay), "day");
+	const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));
+	if (totalMonths < monthsPerYear) return unit(totalMonths, "month");
+	const years = Math.floor(totalMonths / monthsPerYear);
+	const months = totalMonths % monthsPerYear;
+	return months === 0 ? unit(years, "year") : `${unit(years, "year")} ${unit(months, "month")}`;
 }
-async function loadOpaqueKey(opts, format) {
-	return loadKey(opts, format, opaqueFacet);
+function unit(n, name) {
+	return `${n} ${n === 1 ? name : `${name}s`}`;
 }
 //#endregion
-//#region src/cli/signing-key.ts
-const signingFacet = {
-	envVar: "IDS_SIGNING_KEY",
-	formatEnvVar: "IDS_SIGNING_KEY_FORMAT",
-	decode: decodeSigningKey,
-	import: importSigningKey
+//#region src/cli/variants.ts
+const timestampVariant = {
+	inspectMode: "readable",
+	construct(brand, opts) {
+		try {
+			return createTimestampId(brand, codecOpts(opts));
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
 };
-function parseSigningKeyFormat(values, opts) {
-	return parseKeyFormat(values, opts, signingFacet);
-}
-async function loadSigningKey(opts, format) {
-	return loadKey(opts, format, signingFacet);
+const opaqueVariant = {
+	flag: "--opaque",
+	key: {
+		envVar: "IDS_KEY",
+		formatEnvVar: "IDS_KEY_FORMAT",
+		encode: encodeOpaqueKey,
+		decode: decodeOpaqueKey,
+		import: importOpaqueKey
+	},
+	inspectMode: "keyed-readable",
+	construct(brand, opts, key) {
+		try {
+			return createOpaqueTimestampId(brand, {
+				key,
+				...codecOpts(opts)
+			});
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
+};
+const reverseVariant = {
+	flag: "--reverse",
+	inspectMode: "readable",
+	construct(brand, opts) {
+		try {
+			return createReverseTimestampId(brand, codecOpts(opts));
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
+};
+const wrappedVariant = {
+	flag: "--wrapped",
+	key: {
+		envVar: "IDS_WRAPPING_KEY",
+		formatEnvVar: "IDS_WRAPPING_KEY_FORMAT",
+		encode: encodeWrappingKey,
+		decode: decodeWrappingKey,
+		import: importWrappingKey
+	},
+	inspectMode: "unwrap",
+	extraFlags: ["--kind"],
+	construct(brand, _opts, key, values) {
+		const kind = parseKind(values ?? /* @__PURE__ */ new Map());
+		if (kind === void 0) return "--kind is required with --wrapped";
+		if (isKindError(kind)) return kind;
+		try {
+			return createWrappedKeyId(brand, {
+				kind,
+				keys: [key],
+				allowDuplicateBrand: true
+			});
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
+};
+const signedVariant = {
+	flag: "--signed",
+	key: {
+		envVar: "IDS_SIGNING_KEY",
+		formatEnvVar: "IDS_SIGNING_KEY_FORMAT",
+		encode: encodeSigningKey,
+		decode: decodeSigningKey,
+		import: importSigningKey
+	},
+	inspectMode: "verify",
+	construct(brand, opts, key) {
+		try {
+			return createSignedTimestampId(brand, {
+				keys: [key],
+				...codecOpts(opts)
+			});
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
+};
+const conflictPriorityOrder = [
+	signedVariant,
+	reverseVariant,
+	wrappedVariant,
+	opaqueVariant
+];
+const generatePolicy = {
+	default: timestampVariant,
+	selectable: [
+		opaqueVariant,
+		reverseVariant,
+		signedVariant
+	],
+	intrinsicFlags: ["--count", "-c"]
+};
+const inspectPolicy = {
+	default: timestampVariant,
+	selectable: [
+		reverseVariant,
+		wrappedVariant,
+		opaqueVariant,
+		signedVariant
+	],
+	intrinsicFlags: []
+};
+const keygenPolicy = {
+	default: opaqueVariant,
+	selectable: [wrappedVariant, signedVariant],
+	intrinsicFlags: ["--bits"]
+};
+//#endregion
+//#region src/cli/dispatch.ts
+function deriveAllowedFlags(policy) {
+	const flags = new Set(policy.intrinsicFlags);
+	let hasKeyed = policy.default.key !== void 0;
+	for (const v of policy.selectable) {
+		if (v.flag !== void 0) flags.add(v.flag);
+		if (v.key !== void 0) hasKeyed = true;
+		if (v.extraFlags !== void 0) for (const f of v.extraFlags) flags.add(f);
+	}
+	if (hasKeyed) flags.add("--key-format");
+	return flags;
+}
+function resolveVariant(policy, flags) {
+	const selected = conflictPriorityOrder.filter((v) => policy.selectable.some((d) => d === v) && v.flag !== void 0 && flags.has(v.flag));
+	if (selected.length === 0) return policy.default;
+	if (selected.length === 1) return selected[0];
+	return `cannot use ${selected[0].flag} and ${selected[1].flag} together`;
+}
+async function buildCodec(variant, brand, values, opts) {
+	let key;
+	if (variant.key !== void 0) {
+		const format = parseKeyFormat(values, opts, variant.key);
+		if (isKeyFormatError(format)) return format;
+		const keyResult = await loadKey(opts, format, variant.key);
+		if (typeof keyResult === "string") return keyResult;
+		key = keyResult;
+	}
+	return variant.construct(brand, opts, key, values);
 }
 //#endregion
 //#region src/cli/commands/generate.ts
-function runGenerate(args, opts) {
-	const { flags, values, positionals, errors } = splitFlags(args);
-	const unsupported = unsupportedFlagForCommand("generate", flags, new Set([
-		"--count",
-		"-c",
-		"--opaque",
-		"--reverse",
-		"--signed",
-		"--key-format"
-	]));
+async function runGenerate(args, opts) {
+	const allowedFlags = deriveAllowedFlags(generatePolicy);
+	const selectorFlags = new Set(generatePolicy.selectable.map((v) => v.flag).filter((f) => f !== void 0));
+	const { flags, values, positionals, errors } = splitFlags(args, new Set([...allowedFlags].filter((f) => !selectorFlags.has(f))));
+	const unsupported = unsupportedFlagForCommand("generate", flags, allowedFlags);
 	if (unsupported !== void 0) {
 		opts.stderr(unsupported + "\n");
-		return Promise.resolve(1);
+		return 1;
 	}
 	if (errors[0] !== void 0) {
 		opts.stderr(errors[0] + "\n");
-		return Promise.resolve(1);
+		return 1;
 	}
 	const extra = positionals[1];
 	if (extra !== void 0) {
 		opts.stderr(`unexpected argument: ${extra}\n`);
-		return Promise.resolve(1);
+		return 1;
 	}
 	const [brand] = positionals;
 	const count = parseCount(values);
 	if (typeof count === "string") {
 		opts.stderr(count + "\n");
-		return Promise.resolve(1);
-	}
-	const opaque = flags.has("--opaque");
-	const reverse = flags.has("--reverse");
-	const signed = flags.has("--signed");
-	if (reverse && opaque) {
-		opts.stderr("cannot use --reverse and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && opaque) {
-		opts.stderr("cannot use --signed and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && reverse) {
-		opts.stderr("cannot use --signed and --reverse together\n");
-		return Promise.resolve(1);
-	}
-	if (!opaque && !signed && flags.has("--key-format")) {
-		opts.stderr("--key-format requires --opaque or --signed\n");
-		return Promise.resolve(1);
-	}
-	if (opaque) {
-		const format = parseOpaqueKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runOpaqueGenerate(brand ?? "", count, format, opts);
-	}
-	if (signed) {
-		const format = parseSigningKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runSignedGenerate(brand ?? "", count, format, opts);
-	}
-	if (reverse) {
-		let codec;
-		try {
-			codec = createReverseTimestampId(brand ?? "", codecOpts(opts));
-		} catch (err) {
-			opts.stderr(formatCliError(err) + "\n");
-			return Promise.resolve(1);
-		}
-		for (let i = 0; i < count; i++) opts.stdout(codec.generate() + "\n");
-		return Promise.resolve(0);
-	}
-	let codec;
-	try {
-		codec = createTimestampId(brand ?? "", codecOpts(opts));
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return Promise.resolve(1);
-	}
-	for (let i = 0; i < count; i++) opts.stdout(codec.generate() + "\n");
-	return Promise.resolve(0);
-}
-async function runOpaqueGenerate(brand, count, format, opts) {
-	const keyResult = await loadOpaqueKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
 		return 1;
 	}
-	let codec;
-	try {
-		codec = createOpaqueTimestampId(brand, {
-			key: keyResult,
-			...codecOpts(opts)
-		});
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
+	const variant = resolveVariant(generatePolicy, flags);
+	if (typeof variant === "string") {
+		opts.stderr(variant + "\n");
 		return 1;
 	}
-	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
-	return 0;
-}
-async function runSignedGenerate(brand, count, format, opts) {
-	const keyResult = await loadSigningKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
+	if (variant.key === void 0 && flags.has("--key-format")) {
+		opts.stderr("--key-format requires --opaque or --signed\n");
 		return 1;
 	}
-	let codec;
-	try {
-		codec = createSignedTimestampId(brand, {
-			keys: [keyResult],
-			allowDuplicateBrand: true,
-			...codecOpts(opts)
-		});
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
+	const codec = await buildCodec(variant, brand ?? "", values, opts);
+	if (typeof codec === "string") {
+		opts.stderr(codec + "\n");
 		return 1;
 	}
 	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
 	return 0;
 }
 //#endregion
-//#region src/cli/wrapping-key.ts
-const wrappingFacet = {
-	envVar: "IDS_WRAPPING_KEY",
-	formatEnvVar: "IDS_WRAPPING_KEY_FORMAT",
-	decode: decodeWrappingKey,
-	import: importWrappingKey
-};
-function parseWrappingKeyFormat(values, opts) {
-	return parseKeyFormat(values, opts, wrappingFacet);
-}
-async function loadWrappingKey(opts, format) {
-	return loadKey(opts, format, wrappingFacet);
-}
-//#endregion
 //#region src/cli/usage.ts
 function usage() {
 	return [
@@ -432,294 +444,167 @@ function usage() {
 }
 //#endregion
 //#region src/cli/commands/inspect.ts
-function runInspect(args, opts) {
-	const { flags, values, positionals, errors } = splitFlags(args);
-	const unsupported = unsupportedFlagForCommand("inspect", flags, new Set([
-		"--opaque",
-		"--wrapped",
-		"--reverse",
-		"--signed",
-		"--kind",
-		"--key-format"
-	]));
+async function runInspect(args, opts) {
+	const allowedFlags = deriveAllowedFlags(inspectPolicy);
+	const selectorFlags = new Set(inspectPolicy.selectable.map((v) => v.flag).filter((f) => f !== void 0));
+	const { flags, values, positionals, errors } = splitFlags(args, new Set([...allowedFlags].filter((f) => !selectorFlags.has(f))));
+	const unsupported = unsupportedFlagForCommand("inspect", flags, allowedFlags);
 	if (unsupported !== void 0) {
 		opts.stderr(unsupported + "\n");
-		return Promise.resolve(1);
+		return 1;
 	}
 	if (errors[0] !== void 0) {
 		opts.stderr(errors[0] + "\n");
-		return Promise.resolve(1);
+		return 1;
 	}
 	const [input] = positionals;
 	if (input === void 0) {
 		opts.stderr(usage());
-		return Promise.resolve(1);
+		return 1;
 	}
 	const extra = positionals[1];
 	if (extra !== void 0) {
 		opts.stderr(`unexpected argument: ${extra}\n`);
-		return Promise.resolve(1);
-	}
-	const opaque = flags.has("--opaque");
-	const wrapped = flags.has("--wrapped");
-	const reverse = flags.has("--reverse");
-	const signed = flags.has("--signed");
-	if (opaque && wrapped) {
-		opts.stderr("cannot use --wrapped and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (reverse && opaque) {
-		opts.stderr("cannot use --reverse and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (reverse && wrapped) {
-		opts.stderr("cannot use --reverse and --wrapped together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && opaque) {
-		opts.stderr("cannot use --signed and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && wrapped) {
-		opts.stderr("cannot use --signed and --wrapped together\n");
-		return Promise.resolve(1);
+		return 1;
 	}
-	if (signed && reverse) {
-		opts.stderr("cannot use --signed and --reverse together\n");
-		return Promise.resolve(1);
+	const variant = resolveVariant(inspectPolicy, flags);
+	if (typeof variant === "string") {
+		opts.stderr(variant + "\n");
+		return 1;
 	}
-	if (!opaque && !wrapped && !signed && flags.has("--key-format")) {
+	if (variant.key === void 0 && flags.has("--key-format")) {
 		opts.stderr("--key-format requires --opaque, --wrapped, or --signed\n");
-		return Promise.resolve(1);
+		return 1;
 	}
 	const brand = input.slice(0, 3).toLowerCase();
-	if (wrapped) {
-		const kind = parseKind(values);
-		if (kind === void 0) {
-			opts.stderr("--kind is required with --wrapped\n");
-			return Promise.resolve(1);
-		}
-		if (isKindError(kind)) {
-			opts.stderr(kind + "\n");
-			return Promise.resolve(1);
-		}
-		const format = parseWrappingKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runWrappedInspect(brand, input, kind, format, opts);
-	}
-	if (opaque) {
-		const format = parseOpaqueKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runOpaqueInspect(brand, input, format, opts);
-	}
-	if (signed) {
-		const format = parseSigningKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
+	let verifyTimestamp;
+	let verifyCanonical;
+	let verifyNowMs;
+	if (variant.inspectMode === "verify") {
+		const fmtCheck = parseKeyFormat(values, opts, variant.key);
+		if (isKeyFormatError(fmtCheck)) {
+			opts.stderr(fmtCheck + "\n");
+			return 1;
 		}
-		return runSignedInspect(brand, input, format, opts);
-	}
-	if (reverse) {
-		let reverseCodec;
+		let tsCodec;
 		try {
-			reverseCodec = createReverseTimestampId(brand, codecOpts(opts));
+			tsCodec = createTimestampId(brand, codecOpts(opts));
 		} catch (err) {
 			opts.stderr(formatCliError(err) + "\n");
-			return Promise.resolve(1);
+			return 1;
 		}
-		const reverseValidation = reverseCodec["~standard"].validate(input);
-		if (reverseValidation.issues) {
-			opts.stderr(reverseValidation.issues[0].message + "\n");
-			return Promise.resolve(1);
+		const structValidation = tsCodec["~standard"].validate(input);
+		if (structValidation.issues) {
+			opts.stderr(structValidation.issues[0].message + "\n");
+			return 1;
 		}
-		const reverseCanonical = reverseValidation.value;
-		const reverseTimestamp = reverseCodec.extractTimestamp(reverseCanonical);
-		const reverseNowMs = (opts.now ?? Date.now)();
-		opts.stdout(formatInspectOutput({
-			brand,
-			timestamp: reverseTimestamp,
-			canonical: reverseCanonical,
-			input,
-			nowMs: reverseNowMs
-		}));
-		return Promise.resolve(0);
-	}
-	let codec;
-	try {
-		codec = createTimestampId(brand, codecOpts(opts));
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return Promise.resolve(1);
+		verifyCanonical = structValidation.value;
+		verifyTimestamp = tsCodec.extractTimestamp(verifyCanonical);
+		verifyNowMs = (opts.now ?? Date.now)();
 	}
-	const validation = codec["~standard"].validate(input);
-	if (validation.issues) {
-		opts.stderr(validation.issues[0].message + "\n");
-		return Promise.resolve(1);
-	}
-	const canonical = validation.value;
-	const timestamp = codec.extractTimestamp(canonical);
-	const nowMs = (opts.now ?? Date.now)();
-	opts.stdout(formatInspectOutput({
-		brand,
-		timestamp,
-		canonical,
-		input,
-		nowMs
-	}));
-	return Promise.resolve(0);
-}
-async function runWrappedInspect(brand, input, kind, format, opts) {
-	const keyResult = await loadWrappingKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
-		return 1;
-	}
-	let codec;
-	try {
-		codec = createWrappedKeyId(brand, {
-			kind,
-			keys: [keyResult],
-			allowDuplicateBrand: true
-		});
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	const validation = codec["~standard"].validate(input);
-	if (validation.issues) {
-		opts.stderr(validation.issues[0].message + "\n");
-		return 1;
-	}
-	const canonical = validation.value;
-	let lookupKey;
-	try {
-		lookupKey = await codec.unwrap(canonical);
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	opts.stdout(formatWrappedInspectOutput({
-		brand,
-		lookupKey,
-		canonical,
-		input
-	}));
-	return 0;
-}
-async function runOpaqueInspect(brand, input, format, opts) {
-	const keyResult = await loadOpaqueKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
-		return 1;
-	}
-	let codec;
-	try {
-		codec = createOpaqueTimestampId(brand, {
-			key: keyResult,
-			...codecOpts(opts)
-		});
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	const validation = codec["~standard"].validate(input);
-	if (validation.issues) {
-		opts.stderr(validation.issues[0].message + "\n");
-		return 1;
-	}
-	const canonical = validation.value;
-	const timestamp = await codec.extractTimestamp(canonical);
-	const nowMs = (opts.now ?? Date.now)();
-	opts.stderr("note: timestamp assumes IDS_KEY matches the key used at generation; a wrong key yields a plausible but incorrect timestamp\n");
-	opts.stdout(formatInspectOutput({
-		brand,
-		timestamp,
-		canonical,
-		input,
-		nowMs
-	}));
-	return 0;
-}
-async function runSignedInspect(brand, input, format, opts) {
-	let structCodec;
-	try {
-		structCodec = createTimestampId(brand, codecOpts(opts));
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	const validation = structCodec["~standard"].validate(input);
-	if (validation.issues) {
-		opts.stderr(validation.issues[0].message + "\n");
-		return 1;
-	}
-	const canonical = validation.value;
-	const timestamp = structCodec.extractTimestamp(canonical);
-	const nowMs = (opts.now ?? Date.now)();
-	if ((opts.env ?? process.env).IDS_SIGNING_KEY === void 0) {
-		opts.stdout(formatSignedInspectOutput({
+	const codecOrError = await buildCodec(variant, brand, values, opts);
+	if (typeof codecOrError === "string") {
+		if (variant.inspectMode === "verify") opts.stdout(formatSignedInspectOutput({
 			brand,
-			timestamp,
-			canonical,
+			timestamp: verifyTimestamp,
+			canonical: verifyCanonical,
 			input,
-			nowMs
+			nowMs: verifyNowMs,
+			verification: "unavailable"
 		}));
-		return 0;
-	}
-	const keyResult = await loadSigningKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
+		opts.stderr(codecOrError + "\n");
 		return 1;
 	}
-	const verifyResult = await createSignedTimestampId(brand, {
-		keys: [keyResult],
-		allowDuplicateBrand: true,
-		...codecOpts(opts)
-	}).safeVerify(input);
-	if (!verifyResult.ok) {
-		/* v8 ignore next 4 -- defensive: both codecs share the same wire parse so ParseError
-		is unreachable after the createTimestampId pre-validation above passes */
-		if (verifyResult.error !== "verification_failed") {
-			opts.stderr(verifyResult.error + "\n");
+	let canonical;
+	if (variant.inspectMode !== "verify") {
+		const validation = codecOrError["~standard"].validate(input);
+		if (validation.issues) {
+			opts.stderr(validation.issues[0].message + "\n");
 			return 1;
 		}
-		opts.stdout(formatSignedInspectOutput({
-			brand,
-			timestamp,
-			canonical,
-			input,
-			nowMs,
-			verification: "failed"
-		}));
-		return 1;
+		canonical = validation.value;
+	}
+	switch (variant.inspectMode) {
+		case "readable": {
+			const timestamp = codecOrError.extractTimestamp(canonical);
+			const nowMs = (opts.now ?? Date.now)();
+			opts.stdout(formatInspectOutput({
+				brand,
+				timestamp,
+				canonical,
+				input,
+				nowMs
+			}));
+			return 0;
+		}
+		case "keyed-readable": {
+			const timestamp = await codecOrError.extractTimestamp(canonical);
+			const nowMs = (opts.now ?? Date.now)();
+			opts.stderr("note: timestamp assumes IDS_KEY matches the key used at generation; a wrong key yields a plausible but incorrect timestamp\n");
+			opts.stdout(formatInspectOutput({
+				brand,
+				timestamp,
+				canonical,
+				input,
+				nowMs
+			}));
+			return 0;
+		}
+		case "unwrap": {
+			let lookupKey;
+			try {
+				lookupKey = await codecOrError.unwrap(canonical);
+			} catch (err) {
+				opts.stderr(formatCliError(err) + "\n");
+				return 1;
+			}
+			opts.stdout(formatWrappedInspectOutput({
+				brand,
+				lookupKey,
+				canonical,
+				input
+			}));
+			return 0;
+		}
+		case "verify": {
+			const verifyResult = await codecOrError.safeVerify(input);
+			if (!verifyResult.ok) {
+				/* v8 ignore next 4 -- defensive: both codecs share the same wire parse so ParseError
+				is unreachable after the createTimestampId pre-validation above passes */
+				if (verifyResult.error !== "verification_failed") {
+					opts.stderr(verifyResult.error + "\n");
+					return 1;
+				}
+				opts.stdout(formatSignedInspectOutput({
+					brand,
+					timestamp: verifyTimestamp,
+					canonical: verifyCanonical,
+					input,
+					nowMs: verifyNowMs,
+					verification: "failed"
+				}));
+				opts.stderr("verification_failed: verification failed\n");
+				return 1;
+			}
+			opts.stdout(formatSignedInspectOutput({
+				brand,
+				timestamp: verifyTimestamp,
+				canonical: verifyResult.id,
+				input,
+				nowMs: verifyNowMs,
+				verification: "ok"
+			}));
+			return 0;
+		}
 	}
-	opts.stdout(formatSignedInspectOutput({
-		brand,
-		timestamp,
-		canonical: verifyResult.id,
-		input,
-		nowMs,
-		verification: "ok"
-	}));
-	return 0;
 }
 //#endregion
 //#region src/cli/commands/keygen.ts
 function runKeygen(args, opts) {
-	const { flags, values, positionals, errors } = splitFlags(args);
-	const unsupported = unsupportedFlagForCommand("keygen", flags, new Set([
-		"--signed",
-		"--wrapped",
-		"--bits",
-		"--key-format"
-	]));
+	const allowedFlags = deriveAllowedFlags(keygenPolicy);
+	const variantExtraFlags = new Set(keygenPolicy.selectable.flatMap((v) => v.extraFlags ?? []));
+	const { flags, values, positionals, errors } = splitFlags(args, allowedFlags);
+	const unsupported = unsupportedFlagForCommand("keygen", flags, new Set([...allowedFlags].filter((f) => !variantExtraFlags.has(f))));
 	if (unsupported !== void 0) {
 		opts.stderr(unsupported + "\n");
 		return Promise.resolve(1);
@@ -733,10 +618,9 @@ function runKeygen(args, opts) {
 		opts.stderr(`unexpected argument: ${extra}\n`);
 		return Promise.resolve(1);
 	}
-	const signed = flags.has("--signed");
-	const wrapped = flags.has("--wrapped");
-	if (signed && wrapped) {
-		opts.stderr("cannot use --signed and --wrapped together\n");
+	const variant = resolveVariant(keygenPolicy, flags);
+	if (typeof variant === "string") {
+		opts.stderr(variant + "\n");
 		return Promise.resolve(1);
 	}
 	const bits = parseBits(values);
@@ -744,18 +628,19 @@ function runKeygen(args, opts) {
 		opts.stderr(bits + "\n");
 		return Promise.resolve(1);
 	}
-	const format = parseKeygenFormat(values);
+	const format = parseKeyFormatFromFlag(values);
 	if (isKeyFormatError(format)) {
 		opts.stderr(format + "\n");
 		return Promise.resolve(1);
 	}
+	/* v8 ignore next 4 -- defensive guard; all keygenPolicy variants have key defined */
+	if (variant.key === void 0) {
+		opts.stderr("internal: keygen policy variant has no key facet\n");
+		return Promise.resolve(1);
+	}
 	const bytes = new Uint8Array(bits / 8);
 	crypto.getRandomValues(bytes);
-	let encoded;
-	if (signed) encoded = encodeSigningKey(bytes, format);
-	else if (wrapped) encoded = encodeWrappingKey(bytes, format);
-	else encoded = encodeOpaqueKey(bytes, format);
-	opts.stdout(encoded + "\n");
+	opts.stdout(variant.key.encode(bytes, format) + "\n");
 	return Promise.resolve(0);
 }
 //#endregion